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Preface 


Manual Objectives 


This manual provides encyclopedic reference to the DEC Graphical Kernel 

_ System (GKS) and provides examples illustrating DEC GKS function calls. 
DEC GKS is a level 2c GKS implementation. For more information con- 
cerning GKS implementation levels, refer to Chapter 1, Introduction to DEC 
GKS. 


Intended Audience 


This manual is intended for experienced application programmers who 
need to reference information concerning the DEC GKS functions. Readers 
should be familiar with one high-level language and the DIGITAL Command 
Language (DCL). (For more information concerning DCL, refer to the VMS 
DCL Dictionary.) . 


Refer to the DEC GKS Binding Reference Manuals for information specific 
to the binding you use with DEC GKS. The available bindings for DEC GKS 
Version 4.1 are FORTRAN, C, and GKS$. These manuals are designed for 
the experienced user of DEC GKS who needs to know the binding syntax 
and brief argument descriptions. 


Although there are lengthy introductions at the beginning of each of the 
chapters, this manual is not tutorial in nature. New users who need tuto- 
rial information and moderately experienced users needing programming 
suggestions should refer to the DEC GKS User Manual. 


xvii 





Document Structure 


xviii 


This manual is contained in two volumes. Part 1 contains the following 
information: 


Chapter 1, Introduction to DEC GKS, provides an introduction to the 
DEC GKS product and to the format of this reference manual. 


Chapter 2, Compiling, Linking, and Running DEC GKS Programs, 
provides information about DEC GKS and the VMS operating system. 


Chapter 3, Control Functions, provides information concerning the 
establishment of the DEC GKS and workstation environments. 


Chapter 4, Output Functions, provides information concerning the 
generation of output primitives. 


Chapter 5, Output Attribute Functions, provides information concerning 
the output attributes. 


Chapter 6, Transformation Functions, provides information concerning 
the normalization and workstation transformations. 


Chapter 7, Input Functions, provides information concerning input. 


Chapter 8, Segment Functions, provides information concerning the 
storage of output primitives in segments. 

Chapter 9, Metafile Functions, provides information concerning long- 
term storage of graphical images. 


Chapter 10, Error-Handling Functions, provides information concerning 
error-handling by the application program. 


Part 2 of this manual contains the following information: — 


Chapter 11, Inquiry Functions, provides information concerning the 
acquisition of DEC GKS and workstation status information. 


The appendixes, which include the following: 

— Appendix A, DEC GKS Supported Workstations 

— Appendix B, DEC GKS Constants 

— Appendix C, DEC GKS Attribute Values 

- Appendix D, DEC GKS Error Messages 

— Appendix E, DEC GKS Metafile Structures 

— Appendix F, Language-Specific Programming Information 
- Appendix G, DEC GKS Device-Independent Fonts 

— Appendix H, DEC GKS Color Chart 


—- Appendix I, DEC GKS GDPs and Escapes 
— Appendix J, DEC GKS Specific Input Values 


Associated Documents 


“You may find the following documents useful when using DEC GKS: 


DEC GKS User Manual—For programmers who need tutorial informa- 
tion or guides to programming technique. 


DEC GKS FORTRAN Binding Reference Manual—For programmers 
who need specific syntax and argument descriptions for the FORTRAN 
binding. 

DEC GKS GKS$ Binding Reference Manual—For programmers who 
need specific syntax and argument descriptions for the GKS$ binding. 
DEC GKS C Binding Reference Manual—For programmers who need 
specific syntax and argument descriptions for the C binding. 

DEC GKS Device Specifics Reference Manual—For programmers who 
need information about specific devices. 

Building a DEC GKS Workstation Handler System—For programmers 
who need to build DEC GKS workstation graphics handlers. 


Building a DEC GKS Device Handler System—For programmers who 
need to provide support for a device unsupported by the DEC GKS 
graphics handlers. 


DEC GKS Installation Guide—For system managers who install the 
DEC GKS software, including the Run-Time installation. 


NOTE 


Before reading this manual, you should review the DEC GKS 
release notes by typing the following: 


$ HELP GKS RELEASE_NOTES[RETURN] 
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Conventions 


Convention 


$ RUN GKSPROG 


INTEGER X 
X=5 


option, ... 


{output-source, ... ] 


deferral mode 


GKS$K_LINETYPE_DASHED 


XX 


Meaning 


The symbol represents a single 
stroke of the RETURN key on a terminal. 


In interactive examples, the user’s re- 
sponse to a prompt is printed in red; system 
prompts are printed in black. 


A vertical ellipsis indicates that not all of 
the text of a program or program output is 
illustrated. Only relevant material is shown 
in the example. 


A horizontal ellipsis indicates that addi- 
tional arguments, options, or values can be 
entered. A comma that precedes the ellipsis 
indicates that successive items must be 
separated by commas. 


Square brackets, in function synopses and a 
few other contexts, indicate that a syntactic 
element is optional. 


All names of the DEC GKS description table 
and state list entries, and of the workstation 
description table and state list entries, 

are italicized. Also, argument names are 
italicized when they are referenced in the. 
text. 


In the text, constants and function names 
are in uppercase letters. 


Chapter 1 
Introduction to DEC GKS 


The Graphical Kernel System (GKS) is a set of graphics functions that 
can be used by numerous types of graphics applications to produce two- 
dimensional pictures on graphics output devices. GKS is defined by the 

_ ANSI X3.124-1985 and the ISO 7942-1985 standards. DEC GKS adheres 
to both standards. When this manual refers to the GKS standard, the 
reference applies to both standards. 


The GKS standard provides a functional standard, and syntactical standards 
called language bindings. The functional standard determines the effects 
produced by a particular GKS function, but does not specify the function 
name or the number of function parameters. Therefore, a given function in 
two different GKS implementations can produce the same effects, but may 
have a different function name or a different number of parameters. 


DEC GKS implements the functional standard using function names 
beginning with the prefix GKS$. These functions should be used when 
programming with the VMS implementation of DEC GKS. If you use the 
GKS$ functions, you have to edit your program if you want to transport the 
program across systems or across GKS implementations. 


DEC GKS also implements approved syntactical language bindings. For 
DEC GKS Version 4.1, these include the GKS FORTRAN and GKS C 
bindings. The language bindings in general, and specifically the FORTRAN 
and C bindings, provide standard function names and a standard number of 
function parameters. If you write programs to be transported across systems 
or across GKS implementations, you should use the appropriate language 
binding. 
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1.1 GKS Function Categories 


1-2 


The DEC GKS function categories are as follows: 


Control 

Output 

Output attribute 
Transformation 
Input 

Segment 
Metafile 
Error-handling 


Inquiry 


The control functions determine which DEC GKS functions you can call at a 
given point in your program. They also control the buffering of output and 
the regeneration of segments on the workstation surface. 


The output functions produce picture components, called primitives, of the 
following types: 


Polylines—Lines 
Polymarkers—Symbols 

Fill areas—Filled polygons 
Text—Character strings 

Cell Array—Filled cells of a rectangle 


Generalized drawing primitives—A workstation-dependent image such 
as a circle 


Figure 1-1 illustrates possible representations of output primitives. 
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Figure 1-1: Possible DEC GKS Primitives 
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Output attributes affect the appearance of a primitive. For instance, by 
changing the line type attribute, you can produce solid, dashed, dotted, or 
dashed-dotted lines. 


Transformations affect the composition of the graphical picture and the 
presentation of that picture. There are normalization and workstation trans- 
formations. The normalization transformations allow you to use various 
coordinate ranges for different primitives within a single picture. In this 
way, you can use a coordinate range that suits each particular primitive in a 
large picture. 
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The workstation transformations control the portion of the picture that 
you see on the workstation’s surface, and the portion of the surface used to 
display the picture. Using workstation transformations, you can pan across 
a picture, zoom in to a picture, or zoom out of a picture. 


The input functions allow an application to accept data from a user. 


The segment functions store and manipulate groups of primitives called 
segments. 


The metafile functions allow you to store and recall an audit of calls to. 
DEC GKS functions. Using metafiles, you can store a DEC GKS session so 
that another application can interpret that session, thus reproducing the 
picture created by the original application. For more information concerning 
metafiles, refer to Chapter 9, Metafile Functions. 


The error-handling functions allow you to invoke a user-written error han- 
dler when a call to another DEC GKS function generates an error. For more 
information concerning error-handling, refer to Chapter 10, Error-Handling 
Functions. 


The inquiry functions obtain either default or current information from the 
DEC GKS data structures. 


If you need more tutorial information concerning DEC GKS concepts, refer 
to the DEC GKS User Manual. 


1.2 GKS Levels 


The GKS standard defines levels of a GKS implementation that address the 
most common classes of graphic devices and application needs. The levels 
are determined primarily by input and output capabilities, The output level 
values are represented by the characters m, 0, 1, and 2. The input level 
values are represented by the characters a, b, and c. 


The DEC GKS software is a level 2c implementation, incorporating all the 
GKS output capabilities (level 2) and all the input capabilities (level c). This 
manual uses the term DEC GKS when describing the 2c level DEC GKS 
product. 


Figure 1-2 defines the 12 upwardly compatible levels of GKS. DEC GKS 
implements all listed functionality. 


1—4 Introduction to DEC GKS 


Figure 1-2: Functionality by GKS Levels 


Output 
Levels 


input Levels 


No input, minimal control, 
individual attributes, one 
settable normalization 
transformation, subset 

of output and attribute 
functions. 


Basic control, 

bundled attributes, 
multiple normalization 
transformations, all output 
and attribute functions, 
optional metafiles. 


Full output including 
settable bundles, 


‘multiple workstations, 


basic segmentation, no 
workstation independent 
segment storage, 
metafiles. 


Workstation independent 
segment storage 


Request input, set 
Operating mode and 
initialize functions for input 
devices, no pick input. 


Set viewport input priority. 


Request pick, set operating 
mode and initialize 
functions for pick input. 


All of level 1b, above. 





Sample and event input 
no pick. 


All of level mc, above. 


Sample and event input 
for pick. 


ZK-5027-86 
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Pick input is one of the DEC GKS logical input classes used to specify 
segments present on the surface of a device. Request, sample, and event are 
GKS input operating modes. DEC GKS supports all three input operating 
modes. For more information on pick input or operating modes, refer to 
Chapter 7, Input Functions. 


Workstation independent segment storage (WISS) provides a way to store 
segments so that one segment can be transported to different devices. For 
more information, refer to Chapter 8, Segment Functions. 


1.3 Coordinate Range Format 


When specifying a coordinate range, whether the range is located in world 
coordinate space, normalized device coordinate space, or device coordinate 
space, this manual uses a single notation. 


The syntax of this rectangular range specification is as follows: 
([Ix_min, x_max] X [y_min, y_max]) 


Figure 1-3 illustrates the rectangular coordinate area. 
Figure 1-3: Coordinate Range Presentation 


x.min, y-max x_max, ymax 
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For more information concerning the DEC GKS coordinate systems, refer to 
Chapter 6, Transformation Functions. 
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1.3.1 Standard Escape/GDP Data Records 


When calling the functions ESCAPE or GENERALIZED DRAWING 
PRIMITIVE (GDP), you may need to pass a data record. DEC GKS has 
a standard escape/GDP data record that contains up to three integer 
components and four array addresses. 


To use an escape or GDP data record, you need to perform the following 


tasks: 

1. Look up the escape or GDP description in Appendix I, DEC GKS GDPs 
and Escapes, in the DEC GKS Reference Manual. | 

2. Determine the size and contents of the required data record (if one is 
required). 

3. Declare the data record as determined by your particular programming 
language. Each of the seven components of the data record is an integer 
value. The record is read only, passed by reference. 

4. Pass to ESCAPE or GENERALIZED DRAWING PRIMITIVE only the 
data record components required by the escape or GDP. For instance, if 
an escape or GDP only requires 5 data record components, omit values 
from components 6 and 7. 

5. Pass to ESCAPE or GENERALIZED DRAWING PRIMITIVE the exact 


size (in bytes) of the valid portion of the data record, as specified in 
Appendix I, DEC GKS GDPs and Escapes, in the DEC GKS Reference 
Manual. For instance, if an escape or GDP requires 5 valid components 
to the data record, then pass the value 20 as the data record size (each 
component being a longword (4 bytes) in length). 


The DEC GKS standard escape/GDP data record is as follows. 


Position Data Type Description 


1 
2 
3 


Integer Number of integer values passed in the data record. 

Integer Number of real values passed in the data record. 

Integer Number of string addresses passed in the data 
record. 

Integer Address of array of integers with exactly as many 

(address) elements as the number specified in component 
number 1. 
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Position Data Type Description 


5 Integer Address of array of real numbers with exactly as 
(address) many elements as the number specified in compo- 
nent number 2. 
6 Integer Address of array of string lengths with exactly as 
(address) many elements as the number specified in compo- 
nent number 3. 
7 Integer Address of array of string addresses with exactly as 
(address) many elements as the number specified in compo- 


nent number 3. 


After performing a task, some escape functions pass information back to 
you by use of an output data record. This output data record is identical in 
format to the input data record, except that the output record’s components 
are modifiable. You pass the buffer sizes in the first three components 

and the addresses of your buffers in the last four components. DEC GKS 
modifies the first three components to contain the number of elements DEC 
GKS actually used to write output data to each of the corresponding buffers. 


If you are using an escape function and you need to determine the size 
required by the entire output data record buffer, you can pass the value 0 to 
the output record buffer size (documented as the argument record_buffer_ 
length in the ESCAPE function description, described in Chapter 3, Control 
Functions, in the DEC GKS Reference Manual). When you pass the value 0 
as this argument, ESCAPE does not perform the escape, but instead returns 
the size of the output data record to argument record_size. In this manner, 
you can be sure that you declared an output data record buffer that is large 
enough to hold the entire data record. 


To place array addresses in the fourth, fifth, sixth, and seventh components 
of the data record, you need to use a technique specific to your programming 
language. For instance, using VAX FORTRAN, you can use the %LOC 
built-in function. For more information concerning addresses and pointers, 
refer to the documentation set for your programming language. For more 
information concerning the use of %LOC and data records, refer to the choice 
input examples in Chapter 7, Input Functions, in the DEC GKS Reference 
Manual. 


For more information, refer to Appendix I, DEC GKS GDPs and Escapes, 
in the DEC GKS Reference Manual or to the DEC GKS Device Specifics 
Reference Manual. 
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NOTE 


Remember that the DEC GKS input data records have a format 
that is completely different from the DEC GKS standard escape 
/GDP data record format. To review the GKS standard input data 
records, refer to Chapter 7, Input Functions, in the DEC GKS 
Reference Manual. To review the actual data records required by 
the DEC GKS graphics handlers, refer to Appendix J, DEC GKS 
Specific Input Values, in the DEC GKS Reference Manual. 


1.4 Function Presentation Format 


This section describes the format used to provide information about each 

of the DEC GKS functions that use the GKS$ prefix. If you are using a 
language binding, you can find a similar discussion concerning the format of 
binding function descriptions at the beginning of the appropriate language 
binding book. 


The following sections describe the format used to present each of the DEC 
GKS function descriptions. 


1.4.1 Function Description 


Each function description in this manual begins with the English version of 
the function name at the top of the page. This function name is located at 
the top of each subsequent page of the function description. 


The first paragraph of the function description lists the following items: 

¢ The GKS standard function name. _ 

e The valid operating states during which a call to the function is permit- 
ted (for more information, refer to Chapter 3, Control Functions). 


Following the listed information is a short description of the function. 
Within this description is pertinent information about the DEC GKS 
operating state, the DEC GKS description table and state list, and the 
workstation description table and state list. 
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1.4.2 Function Syntax 


The syntax section of the function description lists the syntax of a call 

to the DEC GKS function. The syntax of each DEC GKS function call is 
available for the GKS$, FORTRAN, and C bindings. This syntax includes 
the argument list for each binding. 


Following each syntax section is an argument section that describes each 
GKS$ argument. 


All the DEC GKS functions always return a longword condition status value. 
For a description of the longword status value, refer to Appendix D, DEC 
GKS Error Messages. For information concerning DEC GKS error neneeee 
refer to Chapter 10, Error-Handling Functions. 


1.4.3. Argument Descriptions 
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The argument descriptions for each of the functions appear as follows: 


Arguments 

workstation_id 

data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that identifies an open workstation. 


The arguments passed to DEC GKS functions must be of specific data 
types and they must be passed by specific mechanisms. In the function 
descriptions, these data types are described in the list following each of the 
argument names. 


For each argument, the listed values include: 


e The data type of the argument 
e The type of access made by the function 
e The argument-passing mechanism and form 


‘Most of the passing mechanisms required by DEC GKS functions are the 


default mechanisms of VAX FORTRAN. (This manual clearly documents 
those functions requiring different passing mechanisms in the section 
labeled Arguments within each function description.) Refer to the DEC 
GKS C Binding Reference Manual for information about C binding passing 
mechanisms. 
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The other VAX high-level languages use different default passing mecha- 
nisms. If you are using a high-level language other than FORTRAN, you 
may need to use the argument-passing extensions for that language. The 
include files for some languages (for example, Pascal, BASIC, and PL/I) 
define the default passing mechanisms for each DEC GKS function call. 


Some of the descriptions of data types in this manual are not worded in 
exactly the same manner as in the VMS documentation. For instance, 
when this manual says that an argument is of the data type “real,” the 
corresponding VMS data type is “F_floating point.” The following list 
presents the notation used in this manual and the corresponding VMS 


notation: 
GKS Type/Mechanism Corresponding VMS Type/Mechanism 
Integer Longword integer (signed) 
Real F_floating point 
String Character-coded text string 
Address (record) Longword integer (signed) _ 
This is an address of a data record. 
Type: array (integer) Type: longword integer (signed) 
Mechanism: by reference Mechanism: by reference, array reference 


For a complete discussion of the argument-passing mechanisms, refer to 
the VMS Run-Time Library Routines Reference Manual. For information 
concerning language-specific passing extensions, refer to the appropriate 
VAX high-level language manual. 


1.4.4 Error Message List 


The function descriptions list all errors that can possibly be generated by 
a call to that specific DEC GKS function. For a complete description of the 
error message, the possible cause, and the possible user action, refer to 
Appendix D, DEC GKS Error Messages. 


1.4.5 Program Examples 


Each function description either lists a program example or refers you to 
another example that calls the specified DEC GKS function. All functions 
are written in FORTRAN for use with the VT241, for consistency in 
presentation. FORTRAN-specific constructs are flagged. 
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However, if you are unfamiliar with FORTRAN, you may wish to review the 
following list of FORTRAN-specific constructs used in the program examples 


in this manual: 


Construct 
IMPLICIT NONE 


DATA 
CHARACTER*80 
INTEGER var( 3 ) 


%DESCR 
%VAL 
%REF 


LEN 


%LOC( array ) 


Description 


This statement prevents the VAX FORTRAN compiler 


from implicitly declaring variable names that you have 
not declared. 


This character, located in the first column of the line, 
signifies that the entire line contains a comment. 


This character, located in column six, is a continuation 
character. This character signifies that the previous 
line of code continues onto the line marked with the 
asterisk (*). 

The DATA statement initializes program variables with 
data. 

This identifier is used to declare a character string of 
length 80. 

This declaration declares a three-element array of type 
INTEGER. 


These constructs are argument list built-in functions 
used to pass arguments by descriptor, by value, and by 
reference. 


This construct is a built-in function that returns the 
length of a string. © 


This built-in function returns the address of its argu- 
ment, 


In many of the FORTRAN examples in this book, the following lines of 
code cause the program to pause, so that you can view the image on the 
workstation surface as it is being created. 


Cc Release deferred output. Pause. Type RETURN when you are finished 


C viewing the picture. 


CALL GKS$UPDATE_WS( 1, GKS$K_POSTPONE_FLAG ) 


READ (5, *) 
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Since DEC GKS allows the VT241 to defer, or buffer, output, you have 

to update the screen with a call to UPDATE WORKSTATION in order to 
view the picture created by all previous function calls in the program. The 
FORTRAN READ statement causes the pause in program execution. 


Since the rate of deferral may differ on various workstations, you may wish 
to use the function INQUIRE WORKSTATION DEFERRAL AND UPDATE 
STATES to check the current deferral mode. If the deferral mode is anything 
other than GKS$K_ASAP, you may wish to update the workstation surface 
occasionally when you are debugging your program. If you want to change 
the deferral mode so that the workstation surface is always current, you can 
call the function SET DEFERRAL STATE to change the current deferral 
mode to GKS$K_ASAP. 


For detailed information concerning the DEC GKS deferral mode, refer to 
Chapter 3, Control Functions. 


Also, all program examples include the following line: 
CALL GKSS$OPEN_WS( 1, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 


To convert the program for use with a device other than a VT241, change 
the constant GKS$K_VT240 to the appropriate workstation constant value 
(refer to Appendix A, DEC GKS Supported Workstations), and change any 
device specific information within the program (such as bundled attribute 
values). The device-specific information within each program is noted as 
such. 


After many of the program examples, there is an illustration representing 
the graphical image generated on the surface of the VT241. Since there are 
visual differences between the written page and the workstation surface, the 
image may appear different on your device surface. Also, different devices 
produce different results. 


For instance, the color may be a different hue or lines may not be as 
perfectly smooth as presented in the figure. The figures in this manual serve 
the purpose of showing relative positioning, general color (where applicable), 
and general shape of the graphical image on the surface of the VT241. 
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1.4.6 Returning a Data Record 


The DEC GKS FORTRAN binding does not return data records. This 
restriction conforms with the GKS Standard. Use the GKS$ function with 
FORTRAN if you want to return the data record. 
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Chapter 2 


Pompung: Linking, and Running DEC GKS 
Programs 


The DEC GKS functions that begin with the prefix GKS$ are designed to be 
used on one of the VMS systems. Those functions meet the functional GKS 
standard. In other words, they perform the necessary tasks as designated 
by the GKS standard. 


These functions are in no way meant to meet a syntactical standard. For 
instance, the DEC GKS function CELL ARRAY might have a different 
number of arguments than the cell array function in another GKS 
implementation. As a result, programs written using the GKS$ interface are 
not easily transportable; you have to edit the function names, and possibly 
the number and order of function arguments. However, if you are not coding 
in C or FORTRAN, you must use the GKS$ interface. 


2.1 VMS Programming Considerations 


The specific method for using DEC GKS software depends on the features 
and conventions of each VAX language. This section discusses general issues 
that must be considered when using any VAX language with DEC GKS. 


NOTE 


Some of the VAX languages have language-specific requirements 
for using DEC GKS. For a complete discussion, you should refer to 
Appendix F, Language-Specific Programming Information, before 
coding your programs. For a discussion of the capabilities of each 
of the DEC GKS supported physical devices, refer to the DEC 
GKS Device Specifics Reference Manual. 
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2.1.1 Online Help 


DEC GKS provides an online HELP library. To access this information, type 
the following: 


$ HELP GKS [RETURN] 


Before using the DEC GKS software, you should review the release notes for 
information pertinent to the current release. To review the release notes, 
type the following: 


$ HELP GKS RELEASE NOTES [RETURN] 


2.1.2 Capabilities of Supported Devices 


In many applications, you may wish to write completely device-independent 
programs. In this way, you can run your programs using different devices 
without having to rewrite your programs. The DEC GKS User Manual 
outlines the procedure for device-independent programming using DEC 
GKS. 


However, you may wish to review the range of capabilities of the DEC GKS 
supported devices, or you may wish to write device-dependent subroutines 
within your application. In any instance, it is helpful to review the device- 
specific appendixes in this manual before you begin coding your application. 
The device-dependent appendixes contain information concerning predefined 
bundle index representations, color capabilities, initial input values, bit 
masks as workstation type values, supported escape functions for that 
particular device, and similar information. 


2.1.3 Calling Sequences 


Each DEC GKS function requires a specific calling sequence. The calling 
sequence indicates the elements included in the language statement that 
call the function, and the order of those elements. The three elements are 
the following: 


e Call Type 


High-level VAX languages call DEC GKS functions with CALL state- 
ments or function references. For example, when using FORTRAN, you 
can use a CALL statement to call DEC GKS functions. 
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Function Identifier 


All DEC GKS function names begin with the prefix GKS$. FORTRAN 
binding names begin with an uppercase G, and C binding names begin 
with a lowercase g. The remainder of the name indicates the operation 
performed by the function. 


If writing programs to be transported across systems or across GKS 
implementations, use the appropriate language binding functions. 
Refer to the DEC GKS FORTRAN Binding Reference Manual and the 
DEC GKS C Binding Reference Manual for information concerning the 
FORTRAN and C binding function names. 


Argument List 

Arguments that are passed to DEC GKS functions must be listed in the 
order shown in the syntax descriptions contained in this manual. The 
various language binding functions may have an argument list that is 
different from the corresponding GKS$ function. 


The specific requirements for writing calls and passing arguments to DEC 
GKS functions vary from one language to another. Whatever the language 
of the calling program, DEC GKS functions expect the following: 


Integer arguments to be 32-bit longwords passed by reference. 


Real numbers to be in single-precision, floating-point format passed by 
reference. 


Character strings to be passed by string descriptors. 


Arrays to be passed either by reference or by descriptor, depending on 
the particular DEC GKS function. 


Each language may have specific requirements concerning the language- 
specific calling sequence. For a discussion of language-specific programming 
concerns, refer to Appendix F, Language-Specific Programming Information. 


NOTE 


For all languages that need to declare DEC GKS functions as 
external functions, you should type the appropriate language 
definition file, located in SYS$LIBRARY, to determine the actual 
function parameter identifiers specified in the DEC GKS code. See 
Section 2.1.4.1, Including Definition Files in this chapter for more 
information concerning the language definition files. 
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2.1.4 Constants and Include Files 


DEC GKS constants are symbolic names that are syntactically equivalent to 
literal integer constants. These constants are used in the following ways: 


e As arguments to DEC GKS functions. 


¢ As literal values to which you can compare a returned value from an 
inquiry function (for example, you can compare the return value from a 
call to the function INQUIRE WORKSTATION TYPE, to the constant 
GKS$K_VT125). 


e As literal completion status codes to which you can compare a function 
return value. 


Many DEC GKS functions use constants as arguments, as shown by the 
following function call: ; 


GKS$CLEAR_WS( 1, GKS$K_CLEAR_ALWAYS ) 


You can compare one of the completion status codes to a function return 
value, as follows: 


IF ( GKS$_SUCCESS = GKSSACTIVATE_WS( 1) ) 


Most DEC GKS constants begin with the prefix GKS$K and are defined in 
a definition file. All DEC GKS completion status code constants begin with 
the prefix GKS$_ERROR_ or DECGKS$_ERROR_NEG_ and are defined in 
a separate message file. All DEC GKS bit mask constants begin with the 
prefix GKS$M_. 


You can either specify a literal value as an argument to a DEC GKS 
function, or you can include the language definition files and use a defined 
constant name instead. The use of constants adds to program legibility and 
program documentation. 


To review the list of DEC GKS constants, refer to Appendix B, DEC GKS 
Constants. To review the list of DEC GKS completion status code constants, 
refer to Appendix D, DEC GKS Error Messages. 
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2.1.4.1. Including Definition Files 


You use DEC GKS software primarily by placing calls to DEC GKS functions 
in your program. However, when using DEC GKS, you need statements in 
your program other than calls to GKS functions. The specific statements 
that are needed depend on the VAX language you use. (For more informa- 
tion, refer to Appendix F, Language-Specific Programming Information). 


DEC GKS constants and their values must be made available to all pro- 
grams using DEC GKS regardless of the VAX language you use. All 

VAX high-level languages that use DEC GKS have a method for insert- 

ing an external file into the program source code stream at compile time. 
Incorporating an external file is the method for making DEC GKS constants 
available. 


Your installation kit has been supplied with several files that contain 
DEC GKS constants and separate files that contain DEC GKS completion 
status code constants. All of these files are located in SYS$LIBRARY. 
You incorporate these files into your program with a statement that is 
appropriate to the language you are using. 


For example, BASIC provides the “INCLUDE statement for inserting an 
external file into a program. Therefore, any BASIC program that uses DEC 
GKS should contain the following statement: 


SINCLUDE "SYSS$LIBRARY:GKSDEFS.BAS" 
The language definition files located in SYS$LIBRARY are as follows: 


e GKSDEFS.ADA for VAX Ada 

¢ GKSDEFS.BAS for VAX BASIC 

¢ GKSDEFS.R32 for VAX BLISS 

¢ GKSDEFS.H for VAX C 

e GKSDEFS.LIB for VAX COBOL 

¢ GKSDEFS.FOR for VAX FORTRAN using the GKS$ functions 


¢ GKSDEFS.BND for VAX FORTRAN using the FORTRAN binding 
functions 


¢ GKSDEFS.PAS for VAX Pascal 


¢ GKSDEFS.PLI for VAX PL/I routines declared as procedures (no value 
returns) 


e¢ GKSDEFS.PL2 for VAX PL/I routines declared as functions 
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The completion status code definition files located in SYS$LIBRARY are as 
follows: 


e GKSMSGS.ADA for VAX Ada 

¢ GKSMSGS.BAS for VAX BASIC 

¢ GKSMSGS.R32 for VAX BLISS 

¢ GKSMSGS.H for VAX C 

¢ GKSMSGS.LIB for VAX COBOL 

¢ GKSMSGS.FOR for VAX FORTRAN 
¢ GKSMSGS.PAS for VAX Pascal 

¢ GKSMSGS.PLI for VAX PL/I 


Each file includes comments that describe the exact method for using a 
given definition file. 


2.1.5 Compiling, Linking, and Running Your Programs 


A program that uses DEC GKS function calls should be compiled and exe- 
cuted as any other program. Use the compile command that is appropriate 
to the language you are using and use the RUN command to execute the 
program image. 


DEC GKS functions are supplied as an installed shareable image library. An 
installed shareable image makes linking faster and easier. Also, using DEC 
GKS as a shareable image makes your program’s resulting .EXE file smaller. 


The symbols in the DEC GKS image have been inserted in the system image 
library. Therefore, to link a compiled program to DEC GKS, you only need 
to specify the name of your program’s object file on the command line, as 
follows: 


$ LINK MYPROG.OBJ[RETURN] 


However, if you are using language binding functions in your program, you 
need to link your program’s object file with the appropriate binding object 
library. To link your program to the FORTRAN binding object library, i issue 
the following command: 


$ LINK MYPROG.OBJ, SYS$LIBRARY : GKSFORBND/LIBRARY [RETURN] 
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2.1.6 Logical Names and DEC GKS Programming 


NOTE 


If you are unfamiliar with VMS logical names, then you may wish 
to review the Introduction to VMS before reading this section. 


In many DEC GKS programs, the functions that control the GKS system 
and your workstation appear as follows: 


@ CALL GKS$OPEN_GKS( ’SYSS$ERROR:’ ) 


e CALL GKS$OPEN_WS( 1, GKS$K_CONID_ DEFAULT, 
* GKSS$K_WSTYPE DEFAULT ) 


CALL GKS$ACTIVATE_WS( 1 ) 


Cc Release the DEC GKS and workstation environments. 
CALL GKS$DEACTIVATE_WS( 1 ) 
CALL GKS$CLOSE_WS( 1 ) 
CALL GKS$CLOSE_GKS () 


The following numbers correspond to the numbers in the previous example: 


@ In this call to OPEN GKS, the logical name SYS$ERROR is the only 
argument to the function. This argument tells DEC GKS where to write 
or display generated error messages. 


If you pass the logical name SYS$ERROR (or the value 0), DEC GKS 
translates this logical name and writes the error messages to the 
location specified by the translation. By default, SYS$ERROR translates 
to the logical name TT, which in turn translates to your process’s default 
device connection (error messages appear on your terminal’s display 
surface). 

If you choose, you can specify a VMS file specification as an argument 
to OPEN GKS. In this way, you have a permanent record of generated 
error messages for use during program debugging. 

@ The constant GKS$K_CONID_DEFAULT (or the value 0) tells DEC GKS 
to translate the logical name GKS$CONID in order to determine the 
name of the device connection. 

The constant GKS$K_WSTYPE_DEFAULT (or the value 0) tells DEC 
GKS to translate the logical name GKS$WSTYPE in order to determine 
the name of the workstation type. 
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Consequently, you can use the DEFINE or ASSIGN command on the DCL 
command line to define the logical names to be the connection and type with 
which you are working, as follows: 


language_compile command PROGRAM[RETURN] 
LINK PROGRAM[RETURN] 

DEFINE GKSSCONID +ttbO([RETURN] 

DEFINE GKS$WSTYPE 13 ! VT241 Color([RETURN] 
RUN PROGRAM[RETURN] 


UNNUNM WN 


DEFINE GKSSCONID  tta0[RETURN] 
DEFINE GKS$WSTYPE 12 ! VT125 Black and White[RETURN] 


RUN PROGRAM[RETURN] 


Tin wn 


Before you attempt to define GKS$CONID, you need to perform the following 
tasks: 


1. Make sure that you have allocated the device you need to access. The 
DCL command SHOW DEVICE provides a list of devices on your system 
node. 


2. If it is not allocated, allocate the terminal using the command 
ALLOCATE (you may need special privileges to allocate the device). 


3. Use the command SHOW TERMINAL to make sure that the device’s 
baud rate, parity, and other settings match the settings of the physical 
device. 


4, Define the logical GKS$CONID to be the logical name of the appropriate 
device connection. 


For more information concerning the terminal allocation process, refer to the 
appropriate commands in the VMS DCL Dictionary. 


There may be times when you do not wish to define the DEC GKS logical 
names. In this case, or if you define an invalid value, DEC GKS translates 
several logical names in the following order: 


1. Ifthe logical name GKS$CONID is undefined, DEC GKS uses the logical 
name TT. 


2. DEC GKS then translates TT, which always defaults to your process’s 
default device connection. 


If the logical name GKS$WSTYPE is undefined, then DEC GKS sets the 
device type to be GKS$K_VT240BW (the value 14, a black and white 
VT240). 


2-8 Compiling, Linking, and Running DEC GKS Programs 


The ability to define GKS$CONID and GKS$WSTYPE provides device 
independence. For more information concerning device-independent DEC 
GKS programs, refer to the DEC GKS User Manual. 


2.1.6.1 Specifying Bit Masks as Workstation Type Values 


You have the option of specifying the workstation type value in either a 
hexadecimal, octal, or decimal longword value. In most cases, it is sufficient 
to specify the type value in decimal. 


However, some of the DEC GKS supported devices allow you to pass a bit 
mask in the first word of the longword workstation type value. For example, 
the following workstation type specifies default values for the DIGITAL 
LVP16 plotter: 


$ DEFINE GKSS$WSTYPE  51[RETURN] 


The following hexadecimal workstation type specifies to DEC GKS to use the 
LVP16 plotter in landscape mode, with a paper size of 11 x 17 inches: 


$ DEFINE GKSSWSTYPE %x00020033(RETURN] 


For a complete list of all the available bit masks for a given device, refer to 
the DEC GKS Device Specifics Reference Manual. 
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Chapter 3 


Control Functions 





The control functions establish the DEC GKS and workstation environments, 
and control the workstation surface in a variety of ways. The following list 
presents the control functions by category: 


Category 


GKS Environment 


Workstation Environment 


Display Surface Control 


Additional Control 


GKS Functions 


CLOSE GKS 
OPEN GKS 


ACTIVATE WORKSTATION 
CLOSE WORKSTATION 
DEACTIVATE WORKSTATION 
OPEN WORKSTATION 


CLEAR WORKSTATION 

REDRAW ALL SEGMENTS ON WORKSTATION 
SET DEFERRAL STATE 

UPDATE WORKSTATION 


ESCAPE 
MESSAGE 


In a typical program, you need very few lines of code to tell DEC GKS about 
the type of implementation you are using, the type of device you are using 
for input or output, and the functionality allowed with that particular type 
of device. (Input, output, and other types of devices are called workstations.) 
You begin and end most DEC GKS sessions with lines of code similar to the 


following: 
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Cc Establish the DEC GKS environment; write errors to the device 
represented by the logical name SYSSERROR. 


CALL GKSSOPEN_GKS( ’SYSSERROR:’ ) 


Cc Open the default workstation, on the default device, and give 
Cc the workstation an identification number. If you are working with 
Cc a device which supports input, you can request input after this 
Cc function call, but you cannot generate output. 

CALL GKSS$OPEN_WS( 1, GKS$K_CONID_DEFAULT, 

* GKSS$K_WSTYPE_DEFAULT ) 
Cc Activate the workstation using its identification number. If the 
Cc workstation supports output, you can generate output "primitives" 
Cc after this function call. 

CALL GKSSACTIVATE_WS ( 1) 
c Release the DEC GKS and workstation environments. 


CALL GKS$DEACTIVATE _WS( 1 ) 
CALL GKS$CLOSE_WS( 1 ) 
CALL GKS$CLOSE_GKS() 


The previous code example initiates actions by the DEC GKS kernel that 
involve various operating states, tables, and lists. The tables and lists that 
are accessible at a given time during program execution determine what 
types of tasks you can perform (tasks such as input requests and output 
generation). The following sections discuss the DEC GKS kernel, the DEC 
GKS operating states, and the various tables and lists involved in working 
with DEC GKS. 


3.1 The Kernel, Graphics Handlers, and Description Tables 


The DEC GKS environment consists of the kernel, one or more graphics 
handlers, at least two description tables, and a series of state lists. This 
section discusses all but the state lists, which are described in detail in 

Section 3.1.2. 


The DEC GKS kernel performs basic operations that do not depend on 
capabilities specific to input, to output, or to the use of storage devices. The 
kernel gives the DEC GKS functions access to the information and tools 
necessary to perform properly. The kernel operations include calling certain 
inquiry functions, maintaining certain tables, and issuing calls to graphics 
handlers. 

The DEC GKS graphics handlers consist of functions that the kernel calls 
to perform graphics operations on a particular workstation. The functions 
include obtaining input, relaying output, and responding to inquiries for 
workstation-specific information. 
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DEC GKS supplies graphics handlers for various devices such as the Digital 
VAXstation II/GPX and the VT240. If you are certain which devices your 
DEC GKS programs will use, you should review the DEC GKS Device 
Specifics Reference Manual. In this way, you can become familiar with the 
range of capabilities of a particular device, and you can gain a sense of how 
the supported devices vary. 


The DEC GKS description table contains constant information about the 
GKS implementation you are using. No matter what functions you call in 
your program or no matter what application you run, the information in the 
DEC GKS description table does not change. The DEC GKS kernel uses this 
constant information about DEC GKS to initialize sections of the DEC GKS 
state list, which is described in Section 3.1.2. 


The DEC GKS description table contains information such as the level 

of GKS you are using (with DEC GKS, level 2c), the number of available 

workstation types, the list of workstation types, the maximum allowable 

open workstations, and so forth. The DEC GKS description table is 
contained in the DEC GKS kernel. 


A workstation description table contains constant information about one 
particular device. No matter what functions you call in your program or no 
matter what application you run, the information in a device’s workstation 
description table does not change, as long as you always use the same 
graphics handler. Each graphics handler contains a workstation description 
table describing that particular device. The workstation description table is 
used to initialize sections of the workstation state list, which is described in 
Section 3.1.2. | 


The workstation description table contains information such as the 
workstation type, the workstation category, the device-specific maximum 
coordinate values, the default bundled output attribute values, and so forth. 


3.1.1 Workstations 


A workstation provides a common interface through which a DEC GKS 
application program controls a graphics device. A workstation is usually a 
physical device that has input and/or output capabilities. 

(The GKS$K_WSCAT_MO, GKS$K_WSCAT_MI, and GKS$K_WSCAT_WISS 
workstations are exceptions and are described in Table 3-1.) 
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The various capabilities of the workstation determine the workstation 
category. Every workstation description table has an entry for the work- 
station category of that particular type of workstation. The six workstation 


categories are as follows: 


Table 3~-1: Workstation Categories 


Category 
GKS$K_WSCAT_OUTPUT 


GKS$K_WSCAT_INPUT 


GKS$K_WSCAT_OUTIN 


GKS$K_WSCAT_MO 
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Description 


A workstation of the category GKS$K_WSCAT_ 
OUTPUT can only display graphical images on a 
single display surface. A GKS$K_WSCAT_OUTPUT 
workstation can process all output functions with the 
possible exception of the device-dependent generalized 
drawing primitive (GDP) functions. For more infor- 
mation concerning GDPs, refer to Chapter 4, Output 
Functions. 


A workstation of the category GKS$K_WSCAT_ 
INPUT can only accept input, which must be accepted 
by at least one type of logical input device. A GKS$K_ 
WSCAT_INPUT workstation cannot accept the 
generation of graphical images by DEC GKS output 
functions. For more information concerning input, 
refer to Chapter 7, Input Functions. 


A workstation of the category GKS$K_WSCAT_ 
OUTIN combines the capabilities of GKS$K_WSCAT_ 
OUTPUT and GKS$K_WSCAT_INPUT workstations. 
This type of workstation can display graphic images 
on the workstation surface as well as accept input 
from the logical input devices. Also, this type of 
workstation must include at least one logical input 
device of each class. For more information concerning 
logical input devices, refer to Chapter 7, Input 
Functions. 


A workstation of the category GKS$K_WSCAT_MO 
(Metafile Output) stores image-specific data in a 
file for use in reproducing the graphical image at a 
later time, perhaps in another application program. 
For more information concerning metafiles, refer to 
Chapter 9, Metafile Functions. 
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Table 3-1 (Cont.): Workstation Categories 
Category Description 


GKS$K_WSCAT_MI A workstation of the category GKS$K_WSCAT_MI 
(Metafile Input) allows an application program to 
read and interpret items in a file that contains image- 
specific data used to reproduce a graphic image. The 
file containing the data to be interpreted must be 
produced by a GKS$K_WSCAT_MO workstation. 

For more information concerning metafiles, refer to 
Chapter 9, Metafile Functions. 


GKS$K_WSCAT_WISS A workstation of the category GKS$K_WSCAT_WISS 
(workstation independent segment storage) can store 
output primitives as a single unit during the execution 
of a single application. The group of output primitives 
is called a segment. You can manipulate the group 
of output primitives within the defined segment as a 
single entity. The only way to transfer segments from 
one workstation to another is to store the segment 
in workstation independent segment storage (WISS) 
and then copy that segment to whichever open or 
active workstation you desire. For more information 
concerning segments, refer to Chapter 8, Segment 
Functions. 


3.1.2 Operating States and State Lists 


The previous sections described the constructs, data structures, and tables 
needed to maintain the static attributes of the DEC GKS implementation 
and each workstation. 


The DEC GKS and workstation states are not static. You can generate many 
types of output with many different effects on the surface of the workstation, 
you can use several devices, or you can create different segments. DEC 
GKS must keep track of the current state of both the DEC GKS and the 
workstation environments. 


For example, the DEC GKS kernel must have access to a flag that desig- 
nates whether the DEC GKS software has been initialized, allowing access 
to description tables and other structures. As another example, if you want 
to output to a workstation, DEC GKS must have access to another flag that 
designates whether that workstation is active or not. 
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To keep track of the information that is available to DEC GKS at a given 
time, DEC GKS maintains its operating state and several different state 
lists. 


The DEC GKS operating states are as follows: 


¢ GKS$K_GKCL—GES is closed. 

¢ GKS$K_GKOP—GKS is open. 

e GKS$K_WSOP—At least one workstation is open. 

¢ GKS$K_WSAC—At least one workstation is active. 

¢ GKS$K_SGOP—A segment is open. 

For a better understanding, review the following code example. (It is similar 
to the example presented at the beginning of the chapter.) Following the 
example, Figure 3-1 shows the GKS operating states, the description 
tables and state lists, and the control functions used to change operating 


states. You can use the numbers in the example, in the figure, and in the 
description list to match the lines of code with their effects on the DEC GKS 


operating state. 

0 CALL GKS$OPEN_GKS( 'SYS$ERROR’ ) 

e CALL GKS$OPEN_WS( 1, GKS$K_CONID_DEFAULT, 
* GKS$K_WSTYPE DEFAULT ) 

3) CALL GKSSACTIVATE WS( 1 ) 

4) CALL GKS$CREATE_SEG( 1 ) 

© CALL GKS$CLOSE_SEG() 

6 CALL GKS$DEACTIVATE_WS( 1 ) 

7] CALL GKSS$CLOSE_WS( 1 ) 

tS CALL GKS$CLOSE_GKS () 


The following numbers correspond to the numbers in the previous example 
and to the numbers in Figure 3-1: 


@ Before you invoke DEC GKS, the operating state value is GKS$K_ 
GKCL. When DEC GKS is closed, you can call INQUIRE OPERATING 
STATE VALUE, which returns the current operating state, you can 
call OPEN GKS, or you can call DEC GKS functions to log and handle 
errors. To log and handle errors, DEC GKS maintains the error state 
list. The error state list contains entries that specify the error state and 
the error log file. If you attempt to call DEC GKS functions while DEC 
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GKS is closed (other than those discussed in this paragraph), the call 
generates an error message. For more information, refer to Chapter 11, 
Inquiry Functions, and to Chapter 10, Error-Handling Functions. 


In order to perform more tasks using DEC GKS, you must set the 
operating state to GKS$K_GKOP. To do this, make a call to the control 
function OPEN GKS, and pass to the function the name of an error 
log file so that DEC GKS knows where to write error messages. If you 
specify SYS$ERROR, and if you have not redefined that logical name, 
DEC GKS writes error messages to your terminal. 


Once you open DEC GKS, you have enabled access to the DEC GKS 
description table and the workstation description tables of the supported 
graphics handlers. By calling OPEN GKS, you have also allowed access 
to the DEC GKS state list. The DEC GKS state list contains entries 
that designate information such as the set of open workstations (if any), 
the current normalization number, the current character height, and so 
forth. 


Once DEC GKS is open, you can then specify output attributes (refer 
to Chapter 5, Output Attribute Functions), set normalization transfor- 
mations (refer to Chapter 6, Transformation Functions), obtain values 
from the DEC GKS state list, and obtain values from the DEC GKS and 
workstation description tables (refer to Chapter 11, Inquiry Functions). 
If you attempt to call other functions, DEC GKS generates an error 
message. 


To perform further tasks using DEC GKS (such as requesting input), 
you must open at least one workstation. When you open the first 
workstation, the DEC GKS operating state changes from GKS$K_GKOP 
to GKS$K_WSOP (at least one workstation open). To accomplish this, 
call OPEN WORKSTATION and pass a numeric workstation identifier, 
a physical device name or connection identifier (such as TT, the default 
connection to your terminal), and a workstation type. (See OPEN 
WORKSTATION in this chapter for more information.) The workstation 
identifier is an integer value chosen by you for use in all references in 
the program to a specific, open or active workstation. 


For each workstation you open, there exists a workstation state list. This 
list contains entries that specify whether output is deferred (buffered 

or on hold), whether you have to update the workstation surface 
(redraw the picture to fulfill a request for a picture change), whether 
the workstation surface is empty by DEC GKS definition, whether the 
picture on the surface represents all the requests for output made thus 
far by the application program, and so forth. Many control functions 
affect the values in this table. See Section 3.2.1 for more information. 
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Once at least one workstation is open, you can call all functions except 
those functions that open or close DEC GKS, perform output to a 
workstation, create or insert segments, or write an item to a metafile 
output (GKS$K_WSCAT_MO) workstation (using the function WRITE 
ITEM TO GKSM). If you attempt to call these functions, DEC GKS 

_ produces an appropriate error message. 


© To perform output on a given workstation, you need to activate that 
workstation. When you activate the first workstation, the DEC GKS 
operating state changes from GKS$K_WSOP to GKS$K_WSAC (at 
least one workstation active). To activate a workstation, call the control 
function ACTIVATE WORKSTATION, and pass a workstation identifier 
specifying an open workstation. When DEC GKS is in this operating 
state, you can call all DEC GKS functions except OPEN GKS, CLOSE 
GKS, or CLOSE SEGMENT. If you attempt to call these functions, DEC 
GKS produces an appropriate error message. 


@ When you open a segment, the DEC GKS operating state changes from 
GKS$K_WSAC to GKS$K_SGOP (segment open). To accomplish this 
task, call CREATE SEGMENT and pass a segment name. The segment 
name is chosen by you for use in all references in the program to a 
specific segment. That segment is stored on all active workstations. To 
add output primitives to the segment, you need only call the desired 
DEC GKS output functions. Unless workstation independent segment 
storage (WISS) is open and active during segment creation, segments 
stored on workstations cannot be copied from one workstation to another. 
You can only copy segments from WISS to an open or active workstation; 
you cannot copy a segment from any other type of workstation. 


When you create a segment, DEC GKS creates a segment state list. The 
segment state list contains entries that specify the segment name, the 
set of associated workstations, the detectability of the segment, and so 
forth. 


In the GKS$K_SGOP operating state, you can call all GKS functions 
except those that open or close DEC GKS, those that associate or copy 
the open segment to another workstation, those that attempt to change 
the state of the workstation, those that clear the workstation (CLEAR 
WORKSTATION), or those that create segments (CREATE SEGMENT). 
If you attempt to call those functions, DEC GKS generates an error 
message. 


@ When you close the open segment, the DEC GKS kernel changes the 
operating state from GKS$K_SGOP to GKS$K_WSAC. 


@ If the operating state is GKS$K_WSAC, and if you deactivate the last 
active workstation, the kernel changes the DEC GKS operating state 
from GKS$K_WSAC to GKS$K_WSOP. 
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@ Similarly, if you close the last open workstation, the kernel changes the 
DEC GKS operating state to GKS$K_GKOP. 


© The final call in a single DEC GKS session should be to CLOSE GKS; 
after the call, access to the DEC GKS environment is closed and your 
GKS session ends in an orderly fashion. 


As you end your DEC GKS session, you must close an open segment (if one 
exists), close and deactivate workstations, and close DEC GKS, in the proper 
order. If you do not, your DEC GKS session does not end in an orderly 
fashion. 


For example, if you fail to deactivate and to close an active workstation 
before ending your program, the workstation may not return control to the 
user, depending on the device. 
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Figure 3-1: GKS Operating States and Environment Control 
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3.2 Controlling the Workstation Display Surface 


Depending on the type of device with which you are working, and depending 
on the values of certain entries in the workstation description tables and 
state lists, there may be times during program execution when the picture 
does not contain all the changes previously requested by the application 
program. DEC GKS allows a workstation to delay the actions requested by a 
program in order to utilize most efficiently the capabilities of a workstation. 


Output deferral is one workstation attribute that affects the rate of picture 
generation. By setting the deferral mode, you can buffer the generation of 
output images before transmission to the surface in order to improve overall 
rate of transmission, if a given workstation supports such buffering. Other 
times, you can release buffered output so that the display surface reflects 
the picture defined by the application. 


3.2.1 Output Deferral 


DEC GKS supports four deferral modes for its supported workstations. The 
deferral modes, in increasing order of deferral, are as follows: 


¢ GKS$K_ASAP—Generates output As Soon As Possible. 
¢ GKS$K_BNIG—Generates output Before the Next Interaction Globally. 
¢ GKS$K_BNIL—Generates output Before the Next Interaction Locally. 


¢ GKS$K_ASTI—Generates output At Some Time (as defined by the 
workstation). 


A local interaction happens on the workstation specified at the time of the 
surface update, and a global interaction happens on any open workstation. 
An interaction is a request for input using the DEC GKS input functions. 


Depending on the capabilities of the workstation, it can defer output at 
any level up to the level specified in the call to SET DEFERRAL STATE. 
If the workstation can defer output at the requested level, it does. If the 
workstation cannot defer output at the requested level, it defers output at 
the next supported lower level. 


For example, if you specify GKS$K_ASAP in a call to SET DEFERRAL 
STATE, the workstation must generate output as soon as possible. If 
you specify GKS$K_BNIG, the workstation can defer output at either 
GKS$K_ASAP or GKS$K_BNIG, depending on its capabilities. If you 
specify GKS$K_BNIL, the workstation can defer output on any level up to 
and including GKS$K_BNIL, depending on its capabilities. If you specify 
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GKS$K_ASTI, the workstation can defer output at any of the four levels, 
depending on its capabilities. 


You can specify a suggested level of deferral by calling the function SET 
DEFERRAL STATE. To determine the default deferral state of a given 
workstation type, you can call INQUIRE DEFAULT DEFERRAL STATE 
VALUES. To determine the current state of the deferral mode, you can call 
INQUIRE WORKSTATION DEFERRAL AND UPDATE STATES. 


Writing applications with other graphics programs, you need to “flush the 
output buffer” in order to include all output in your picture. The DEC GKS 
equivalent of this action is to “release deferred output” (if there is any). To 
see if generated output has been deferred by the workstation, you call the 
function INQUIRE WORKSTATION DEFERRAL AND UPDATE STATES. 
To release deferred output without updating the screen in any other way, 
call the function UPDATE WORKSTATION and pass the argument GKS$K_ 
POSTPONE_FLAG. For example, the VT125 and the VT240 defer output by 
default. If you are using those devices, you need to release deferred output 
if you want to place the current image on the workstation surface. 


3.2.2 Implicit Surface Regenerations 


Suppressed implicit regeneration of the currently generated output prim- 
itives is the second workstation attribute that can place the workstation 
surface out of date. 


If you request a change to an output attribute bundle index, a change 

to a segment attribute, or a change to the current workstation window 

or viewport, the workstation can either make the change to the surface 
dynamically (GKS$K_IMM) or can implicitly regenerate the entire picture in 
order to comply with the requested change (GKS$K_IRG). 


Whether a workstation makes the change dynamically or requires an 
implicit regeneration is a static capability of the particular workstation. 
You can call either the function INQUIRE DYNAMIC MODIFICATION OF 
SEGMENT ATTRIBUTES or INQUIRE DYNAMIC MODIFICATION OF 
WORKSTATION ATTRIBUTES to determine if a workstation can make a 
certain change immediately or if the picture must be implicitly regenerated. 


If a workstation makes changes dynamically, then only the output primitives 
in the picture that are affected by the change are regenerated and the 
surface does not become out of date. For instance, for many of the supported 
workstations, a call to the function SET COLOR REPRESENTATION 

(refer to Chapter 5, Output Attribute Functions) changes color table entries 
dynamically. 
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When an implicit regeneration occurs, the workstation clears the surface, 
implements the change, and then redraws only the segments on the work- 
station surface. You lose all output primitives not contained in segments. 
For instance, for many of the supported workstations, a call to the function 
SET POLYLINE REPRESENTATION (refer to Chapter 5, Output Attribute 
Functions) causes an implicit regeneration on many workstations. 


If a workstation makes changes by implicit regeneration, the workstation 
may or may not regenerate the workstation surface at that point in the 
program to implement the change. The implicit regeneration mode entry in 
the workstation state list specifies whether the workstation currently allows 
implicit regenerations, or if it suppresses them, leaving the workstation 
surface out of date. You can call the function INQUIRE WORKSTATION 
DEFERRAL AND UPDATE STATES to determine if the workstation is ~ 
allowing regenerations (GKS$K_IRG_ALLOWED) or suppressing them 
(GKS$K_IRG_SUPPRESSED). 


Many of the DEC GKS supported devices suppress implicit regenerations 
because of the possible loss of output primitives caused by an allowed 
regeneration. If you wish to change the implicit regeneration mode entry in 
the workstation state list, you can call the function SET DEFERRAL STATE. 
Suppressing implicit regenerations allows you to make many changes to the 
picture without incurring the overhead of a regeneration for every change. 


_ When you are ready to update the workstation surface, you can call 
UPDATE WORKSTATION, passing GKS$K_PERFORM_FLAG, to per- 
form the single implicit regeneration. Remember that if you call UPDATE > 
WORKSTATION to force a surface regeneration, you lose all primitives not 
contained in segments. 


3.2.3 Workstation Surface State List Entries 


When controlling the workstation surface, you should be aware of the 
display surface empty and the new frame action necessary at update entries 
in the workstation state list. 


Several of the control functions clear the workstation surface if the display 
surface empty entry is GKS$K_EMPTY. Under certain conditions, when 
you are working with different clipping rectangles and generalized drawing 
primitives (GDPs), the entry may contain GKS$K_NOTEMPTY when the 
surface is actually empty. In such situations, when the entry contains 
GKS$K_NOTEMPTY, the application program must decide whether or not 
there exists any “invisible” output to the workstation surface. 
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Also, you may wish to check the new frame action necessary at update 
entry to determine if an implicit regeneration will occur if you update the 
surface by calling UPDATE WORKSTATION (passing GKS$K_PERFORM_ 
FLAG as an argument). If the new frame entry is GKS$K_NEWFRAME_ 
NOTNECESSARY, then you can update the surface without the fear of los- 
ing primitives not contained in segments. If the new frame entry is GKS$K_ 
NEWFRAME_NECESSARY, then a call to UPDATE WORKSTATION with 
the GKS$K_PERFORM_FLAG argument will cause an implicit regeneration, 
causing all primitives not contained in segments to be lost. 


For more information, refer to Chapter 11, Inquiry Functions. 


3.3 Control Inquiries 


The following list presents the inquiry functions that you should use to 
obtain control function information when writing device-independent code: 


INQUIRE SET OF ACTIVE WORKSTATIONS 

INQUIRE WORKSTATION DEFERRAL AND UPDATE STATES 
INQUIRE DYNAMIC MODIFICATION OF WORKSTATION 
ATTRIBUTES 

INQUIRE WORKSTATION MAXIMUM NUMBERS 
INQUIRE LEVEL OF GKS 

INQUIRE WORKSTATION STATE 

INQUIRE SET OF OPEN WORKSTATIONS 

INQUIRE WORKSTATION TYPE 

INQUIRE OPERATING STATE VALUE 

INQUIRE LIST OF AVAILABLE WORKSTATION TYPES 
INQUIRE WORKSTATION CATEGORY 


For more information concerning device-independent programming, refer to 
the DEC GKS User Manual. 


3.4 Function Descriptions 


This section describes the control functions in detail. 
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ACTIVATE WORKSTATION 


ACTIVATE WORKSTATION 


Operating States: WSOP, WSAC 


Description 


Syntax 


The function ACTIVATE WORKSTATION activates the specified work- 
station, allowing all subsequently generated output to be sent to the 
workstation. 


You must open DEC GKS and you must open the workstation you wish to 
activate before calling ACTIVATE WORKSTATION. If the newly activated 
workstation is the only active workstation, DEC GKS changes the operating 
state from GKS$K_WSOP (at least one workstation open) to GKS$K_WSAC 
(at least one workstation active). 


GKS$ACTIVATE_WS _ (workstation_id) 
GACWK_  (workstation_id) 
gactivatews (workstation_id) 


Arguments 


workstation_id 


data type: integer 

access: read-only 

mechanism: by reference 

This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in this chapter). 
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ACTIVATE WORKSTATION 


Error Messages 


20 
25 
29 
33 
35 


43 


Program Example 


Completion 
Status Code 


DECGKS$_ERROR_NEG_20 


GKS$_ERROR_6 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_29 
GKS$_ERROR_33 
GKS$_ERROR_35 


GKS$_ERROR_43 


Message 


GKS not in proper state: GKS in 
the ERROR state in routine **** 


GKS not in proper state: GKS 
shall be either in the state WSOP 


or in the state WSAC in routine 
RK 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is active in 
routine **** 


Specified workstation is of cate- 
gory MI in routine **** 


Specified workstation is of cate- 
gory INPUT in routine **** 


Maximum number of simultane- 
ously active workstations would be 
exceeded in routine **** 


Example 3-1 illustrates the use of many of the DEC GKS control functions, 


including ACTIVATE WORKSTATION. | 
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ACTIVATE WORKSTATION 


Example 3-1: CLEAR WORKSTATION and the GKS Control Functions 





Cc This program writes a text string to the screen, and then 
Cc Clears the screen on the condition that it is not already clear. 
IMPLICIT NONE 
INCLUDE ’SYS$LIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID 
REAL START_X, START_Y, LARGER 
DATA START_X / 0.1 /, START_Y / 0.5 /, LARGER / 0.03 /, 
* WS ID / 1 / 


CALL GKSSOPEN_GKS( ‘’SYSS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKSS$K_CONID_DEFAULT, GKSS$K_VT240 ) 
CALL GKSS$ACTIVATE_WS( WS_ID ) 
C Write a line of text to the screen at a legible text height. 
CALL GKS$SET_TEXT_HEIGHT( LARGER ) 
CALL GKS$TEXT( START_X, START_Y, ‘GKS$CLEAR_WS should erase this’) 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE FLAG ) 

READ (5, *) 
Cc Clear the screen conditionally 


CALL GKS$CLEAR_WS( WS_ID, GKS$K_CLEAR_CONDITIONALLY ) 


Cc Release the GKS and workstation environments. 
CALL GKS$DEACTIVATE_WS ( WS_ID ) 
CALL GKSS$CLOSE_WS ( WS_ID ) 
CALL GKS$CLOSE_GKS () 
END 


The following numbers correspond to the numbers in the previous example: 


@ You must call the function OPEN GKS to establish the DEC GKS 
environment. The logical name, SYS$ERROR, usually defaults to the 
standard output device (the terminal surface). DEC GKS translates the 
logical name to determine where to output error messages. You may 
find it convenient to pass a file specification so that you can review the 
generated error messages at any given time. 


@ When you initialize the specified workstation environment, you assign 
the workstation a numeric identifier (in this example, the number 1), 
a device name (in this example, DEC GKS translates the logical name 
GKS$CONID to determine the device name), and a workstation type (in 
this example, GKS$K_VT240 represents the VT241 device type). 
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ACTIVATE WORKSTATION 


If you choose not to use DEC GKS constants and you wish to use default 
values, you can replace the constants with the value 0. 


For more information concerning the constants used here, refer to OPEN 
WORKSTATION in this section or to Chapter 1, Introduction to DEC 
GKS. 


© When activating a workstation using ACTIVATE WORKSTATION, use 
the workstation identifier that you specified as the first argument in the 
call to function OPEN WORKSTATION (in this example, the value 1). 


@ Using default windows and viewports, the function TEXT outputs a 
character string starting at the world coordinates (0.1, 0.5). 


For more information concerning the coordinate systems, refer to 
Chapter 6, Transformation Functions. For more information concerning 
text output, refer to Chapter 4, Output Functions. 

© The function CLEAR WORKSTATION, when passed GKS$K_CLEAR_ 
CONDITIONALLY, clears the workstation under the condition that the 
surface contains output primitives. Since the previous function call 
wrote a character string to the workstation surface, this call clears the 
screen. 

@ When deactivating and closing the open workstation, pass the nu- 
meric workstation identifier previously specified in the call to OPEN 
WORKSTATION (in this example, the value 1). 
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CLEAR WORKSTATION 


CLEAR WORKSTATION 


Operating States: WSOP, WSAC 


Description 


Syntax 


The function CLEAR WORKSTATION performs the tasks in the following 

order: 

1. Generates all deferred output (see SET DEFERRAL STATE in this 
section). 

2. Ifthe display surface empty workstation state list entry is GKS$K_ 
NOTEMPTY, this function always clears the surface. If the surface 
is empty (GKS$K_EMPTY), then this function only clears the screen 
if you specify GKS$K_CLEAR_ALWAYS as an argument. If no other 
workstations are associated with the segment, the segment is deleted. 
For more information, refer to Chapter 8, Segment Functions. 


After executing this function, DEC GKS sets the display surface empty work- 
station state list entry to GKS$K_EMPTY, the workstation transformation 
update state entry to GKS$K_NOTPENDING, and the new frame necessary 
at update state list entry to GKS$K_NEWFRAME_NOTNECESSARY. 


GKS$CLEAR_WS_ (workstation_id, flag) 
GCLRWK_=(workstation_id, control_flag) 
gclearws (workstation_id, clearflag) 
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CLEAR WORKSTATION 


Arguments 


workstation_id 


data type: integer 
access: read-only 
‘mechanism: by reference 


This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in this chapter). 


flag 

data type: integer 
access: read-only 
mechanism: by reference 


This argument determines under which condition DEC GKS clears the 
screen. This argument can be either of the following values or constants: 


Value Constant Description 

0 GKS$K_CLEAR_CONDITIONALLY Clear if the surface is not 
empty. 

1 GKS$K_CLEAR_ALWAYS Clear the workstation. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the ERROR state in routine **** 

-37 DECGKS$_ERROR_NEG_37 Error in device handler during 


event flag allocation in routine 
eR 


3-20 Control Functions 


Error 
Number 


20 


25 


33 


35 


Program Example 


Completion 
Status Code 


GKS$_ERROR_6 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_33 


GKS$_ERROR_35 


CLEAR WORKSTATION 


Message 


GKS not in proper state: GKS 
shall be either in the state WSOP 


or in the state WSAC in routine 
sakes 


Specified workstation identifier is 
invalid in routine **** 

Specified workstation is not open 
in routine **** 

Specified workstation is of cate- 
gory MI in routine **** 


Specified workstation is of cate- 
gory INPUT in routine **** 


Refer to Example 3-1 in this section for a program example using a call to 
CLEAR WORKSTATION. 
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CLOSE GKS 


CLOSE GKS 


Operating States: GKOP 


Description 


The function CLOSE GKS releases the DEC GKS buffers, closes the error 
log file, and deletes it if empty. CLOSE GKS releases the DEC GKS 
description table, the DEC GKS state list, and the workstation description 
tables. A call to CLOSE GKS must end each DEC GKS session. 


You must call both DEACTIVATE WORKSTATION for each active worksta- 
tion and CLOSE WORKSTATION for each open workstation before you call 
CLOSE GKS. If you do not, DEC GKS logs an error message. 


A call to CLOSE GKS changes the DEC GKS operating state from GKS$K_ 
GKOP (GKS open) to GKS$K_GKCL (GKS closed). 
Syntax 


GKS$CLOSE_GKS /() 
GCLKS /() 
gclosegks /() 
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Error Messages 


Error Completion 
Number Status Code 
—20 DECGKS$_ERROR_NEG_20 


2 GKS$_ERROR_2 


Program Example 


CLOSE GKS 


Message 
GKS not in proper state: GKS in 
the ERROR state in routine **** 


GKS not in proper state; GKS 
shall be in the state GKOP in 
routine **** 


Refer to Example 3—1 in this section for a program example using a call to 


CLOSE GKS. 
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CLOSE WORKSTATION 


CLOSE WORKSTATION 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function CLOSE WORKSTATION updates the workstation (equivalent 
to a call to UPDATE WORKSTATION with the GKS$K_PERFORM_ 
FLAG argument), closes a workstation opened by a previous call to OPEN 
WORKSTATION, and releases a specified workstation’s state list. CLOSE 
WORKSTATION deassigns the channel used for input/output to the device 
and removes the workstation from the set of open workstations in the DEC 
GKS state list. 


If you call this function to close the last open workstation, this function 
changes the DEC GKS operating state from GKS$K_WSOP (at least one 
workstation open) to GKS$K_GKOP (GKS open). 


Be sure to deactivate a workstation with a call to DEACTIVATE 
WORKSTATION before you attempt to close a workstation with CLOSE 
WORKSTATION. If you do not, DEC GKS logs an appropriate error 
message. 


GKS$CLOSE_WS _ (workstation_id) 
GCLWK _ (workstation_id) 
gclosews_ (workstation_id) 
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CLOSE WORKSTATION 


Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in this chapter). 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the ERROR state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 

20 GKS$_ERROR_20 Specified workstation identifier is. 

. invalid in routine **** 

25 GKS$_ERROR_25 Specified workstation is not open 
in routine **** 

29 GKS$_ERROR_29 Specified workstation is active in 
routine **** 

147 GKS$_ERROR_147 Input queue has overflowed in 


routine **** 


Program Example 


Refer to Example 3-1 in this section for a program example using a call to 
CLOSE WORKSTATION. 
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DEACTIVATE WORKSTATION 


Operating States: WSAC 


Description 


The function DEACTIVATE WORKSTATION deactivates a specific worksta- 
tion so that subsequent output will not be sent to that workstation. A call to 
this function removes the workstation from the set of active workstations in 
the DEC GKS state list. Segments stored on the workstation are retained. 


If a call to this function deactivates the last active workstation, this function 
changes the DEC GKS operating state from GKS$K_WSAC (at least one 
workstation active) to GKS$K_WSOP (at least one workstation open). 


You must deactivate a workstation before you can close that workstation. 
Also, you must deactivate and close all workstations (if applicable) before 
you can close DEC GKS. Otherwise, DEC GKS logs an appropriate error 
message. 


Syntax 
GKS$DEACTIVATE_WS_  (workstation_id) 
GDAWK_ = (workstation_id) 
gdeactivatews (workstation_id) 
Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in this chapter). 
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Error Messages 


20 
30 
33 


35 


Program Example 


DEACTIVATE WORKSTATION 


Completion 
Status Code 


DECGKS$_ERROR_NEG_20 


GKS$_ERROR_38 


GKS$_ERROR_20 
GKS$_ERROR_30 
GKS$_ERROR_33 


GKS$_ERROR_35 


Message 


GKS not in proper state: GKS in 
the ERROR state in routine **** 
GKS not in proper state: GKS 
shall be in the state WSAC in 
routine **** 

Specified workstation identifier is 
invalid in routine **** 

Specified workstation is not active 
in routine **** 


Specified workstation is of cate- 
gory MI in routine **** 


Specified workstation is of cate- 
gory INPUT in routine **** 


Refer to Example 3-1 in this section for a program example using a call to 
DEACTIVATE WORKSTATION. 
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ESCAPE 


Operating States: GKOP, WSOP, WSAC, SGOP 
Description 


The function ESCAPE provides a method for individual DEC GKS imple- 
mentations to access capabilities of a specific workstation that are not fully 
utilized by other functions. For example, the DEC GKS implementation uses 
this function call to produce a hardcopy dump of a VT125/VT240 terminal 
screen or to set the plotter pen speed on an LVP16 workstation. 


DEC GKS Device Specifics Reference Manual describes the level of support 
for the DEC GKS escape functions. For more information concerning the 
available escapes, refer to the DEC GKS Device Specifics Reference Manual. 


SYNTAX 


GKS$ESCAPE  (function_id, in_data_record, in_record_size, 
out_data_record, out_record_size, 
total_record_size) 


GESC  (fun_id, dim_idr, idr, max_odr, len_odr, odr) 
gescape (function, indata, bufsize, outdata, escout_size) 


Arguments 
function_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the escape function identifier. 
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in_data_record 


data type: address (record) 
access: read-only 
mechanism: by reference 


This argument is a pointer to the input data record buffer. For more 
information concerning the structure of the input data record, refer to 
Chapter 1, Introduction to DEC GKS. 


in_record_size 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the size of the input data record in bytes. This argument 
should be the exact size of the required input data record. 


out_data_record 


data type: address (record) 
access: modifiable 
mechanism: by reference 


This argument is a pointer to the output data record buffer. For more 
information concerning the structure of the output data record, refer to | 
Chapter 1, Introduction to DEC GKS. 


our_record_size 


data type: integer 
access: modifiable 
mechanism: by reference 


On input, this argument contains the size of the output data record buffer 
in bytes. On output, DEC GKS writes the amount of the buffer actually 
containing the output data record. If the argument total_record_size is 
larger than out_record_size, then you know that DEC GKS truncated the . 
output data record when writing to the buffer. 


If this argument is the value 0, DEC GKS only checks for errors and then 
writes the size of the output data record to total_record_size; the escape is 
not performed. In this way, you can obtain the actual size of the data record 
to compare it to your buffer space. 
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total_record_size 


data type: integer 
access: write-only 
mechanism: by reference 


This argument is the total size of the output data record in bytes. If the 
total size of the output data record does not match the size of the output 
buffer, you know that the record was either truncated to fit in the allocated 
space or was smaller than the allocated space. 


Error Messages 


Program 
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Error Completion 

Number Status Code Message 

-20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the ERROR state in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 
shall be in one of the states GKOP, 
WSOP, WSAC, or SGOP in routine 
Ke 

180 GKS$_ERROR_180 Specified escape function is not 
supported in routine **** 

181 GKS$_ERROR_181 Specified escape function iden- 
tification is invalid in routine 

hike 

182 GKS$_ERROR_182 Contents of escape data record are 
invalid in routine **** 

Example 


Example 3-2 illustrates the use of the function ESCAPE. To achieve the 
same effects, you should connect a printer to the printer port of the VT241 
terminal. Following the program example, Figure 3-2 illustrates the 
program’s effect on a VT241 workstation. 


Functions 


ESCAPE 


Example 3-2: Using the Escape Function 





Cc This program outputs a tall, thin house from a VT240 screen to 
c an attached printer. 
IMPLICIT NONE 
INCLUDE 'GKSDEFS.FOR’ 
INTEGER WS_ID, NUM _POINTS, IN_DATA( 7 ), 
* IN SIZE, OUT_DATA( 7 ), OUT_RECORD SIZE, 
*TOTAL RECORD SIZE, LIST _INTS( 1), LIST_INTS PTR 
REAL PX ( 9 ), PY (9 ) 
DATA PX / .4, .1, .1, .4, .25, .1, .4, .4, .1/ 
DATA PY / .1, .1, .7, «7, «9, «7, «1, «7, «1 / 
DATA NUM_POINTS / 9 /, IN_SIZE / 16 /, WS_ID / 1 /, 
* OUT_RECORD SIZE / 28 / 


EQUIVALENCE( IN _DATA( 4 ), LIST_INTS PTR ) 
LIST _INTS PTR = %LOC( LIST_INTS ) 


CALL GKS$OPEN_GKS( ’SYSSERROR:’ ) 
CALL GKSS$OPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE _WS( WS_ID ) 


CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 
Cc Initialize escape data record... 


IN DATA( 1 ) 
IN DATA( 2 ) 
IN DATA( 3 ) 
LIST_INTS( 1 


1 


0 
0 


~ i id 


WS_ID 


CALL GKS$ESCAPE( GKS$K_ESC_PRINT, IN_DATA, IN SIZE, 
* OUT_DATA, OUT_RECORD SIZE, 
* TOTAL RECORD SIZE ) 


CALL GKS$DEACTIVATE WS( WS_ID ) 
CALL GKSSCLOSE_WS( WS_ID ) 

CALL GKSS$CLOSE_| GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ These arrays contain the house’s X and Y world coordinates. For exam- 
ple, the first element of the array PX is the X value of the first point, and 
the first element of the array PY is the Y value of the first point (.4, .1). 
This program uses the default world coordinate plane with the starting 
point (0, 0), the maximum X value 1.0, and the maximum Y value 1.0. 
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@ You must correctly initialize the data record size arguments. According 
to the description of the GKS$K_ESC_PRINT escape, the input data 
record is 16 bytes long (4 longword components). The initial size of the 
output data record is 28 bytes long (ESCAPE ignores the output data 
record for GKS$K_ESC_PRINT). 


If you initialize the argument out_record_size to be the value 0, DEC 
GKS does not perform the escape, but instead returns the length of the 
output data record to the argument total_record_size. This functionality 
is useful when you are not sure if your output data record buffer is large 
enough. 


This code outputs a tall, thin house to the VT241 terminal screen. 


The input data record passed to ESCAPE must contain the workstation 
identifier of the device containing the picture to be printed. In this 
example, the variable ws_id represents the VT241 screen. 


For a complete description of the DEC GKS standard escape data record 
format, refer to Chapter 1, Introduction to DEC GKS. For a complete 
description of the DEC GKS supported escapes and their data record 
requirements, refer to Appendix I, DEC GKS GDPs and Escapes. 


© The call to ESCAPE outputs the picture to the attached printer. 


Figure 3-2 shows the screen of a VT241 terminal after the program has run 
to completion. 
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Figure. 3-2: Using the Escape Function—VT241 
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MESSAGE 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function MESSAGE allows an application program to deliver a message 
to the user at an implementation-dependent location on the workstation 
surface, or on a separate device associated with the workstation. (For 
example, you may wish to send a message to the user stating the need to 
change the paper in the plotter before you regenerate the picture.) 


For information on the workstation-specific capabilities of MESSAGE, refer 
to the DEC GKS Device Specifics Reference Manual. 


SYNTAX 


GKS$MESSAGE _ (workstation_id, message) 

GMSG _(workstation_id, message) 

GMSGS - subset (workstation_id, |_message, message) 
gmessage (worksiation_id, message) 


Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in this chapter). 
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message 

data type: string 

access: read-only 
mechanism: by descriptor 


MESSAGE 


This argument is the text of the message to be delivered to the specified 


workstation. 


Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
—39 DECGKS$_ERROR_NEG_39 
7 GKS$_ERROR_7 

20 GKS$_ERROR_20 

25 GKS$_ERROR_25 

36 GKS$_ERROR_386 

101 GKS$_ERROR._101 


Program Example 


Message 


GKS not in proper state: GKS in 
the ERROR state in routine **** 


Descriptor is not acceptable in 
routine **** 


GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is 
Workstation Independent Segment 
Storage in routine **** 


Number of points is invalid in 
routine **** 


Example 3-3 illustrates the use of the function MESSAGE. To achieve the 


same effects, you need to do the following: 
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L. 


Determine the device connection identifier of the printer you want to use 
as a workstation. The printer must be attached to your host system, not 
to your terminal. The DIGITAL Command Language (DCL) command 
SHOW DEVICE may assist you. 


Allocate that device for your use using the DCL command ALLOCATE. 
(You may need special privileges to allocate a device.) 


Use the DCL command SHOW TERMINAL for the allocated device, 

to determine whether the baud rate, parity, and other terminal 
characteristics match the communications settings on the printer. For 
more information on these settings, refer to the programming guide for 
the printer. 


Use the DCL command DEFINE to define GKS$CONID as the connec- 
tion identifier for the allocated device, and GKS$WSTYPE as the type 
of printer you are using. For more information concerning the possible 
workstation types, refer to the appropriate appendix in this manual. 


Following the program example, Figure 3-3 illustrates the program’s effect © 
on a VT241 workstation. 


Example 3-3: Sending a Message to the User 


Cc 
Cc 
c 





This program outputs a "tall, thin house" to 

an LA100 and then prints a message on the VT241 terminal 
screen. 

IMPLICIT NONE 

INCLUDE '’SYSSLIBRARY:GKSDEFS. FOR’ 

INTEGER WS_SCREEN, WS PRINTER, NUM_POINTS 

REAL PX ( 9 ), PY (9 ) 

DATA PX / .4, .1, .1, .4, .25, .1, .4, .4, .1 / 

DATA PY / .1, .1, .7, «7, -9, -7, -1, .7, -1 / 

DATA NUM_POINTS / 9 /, WS_PRINTER / 1 /, WS SCREEN / 2 / 


CALL GKSSOPEN_GKS( 'SYSSERROR:’ ) 

CALL GKSS$OPEN_WS( WS_PRINTER, GKS$K_CONID_ DEFAULT, 
* GKS$K_WSTYPE DEFAULT ) 

CALL GKSSACTIVATE_WS( WS_PRINTER ) 

CALL GKSSOPEN_WS( WS_SCREEN, ‘/TT:’, GKS$K_VT240 ) 
CALL GKSSACTIVATE_WS( WS_SCREEN ) 


(continued on next page) 
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Example 3-3 (Cont.): Sending a Message to the User 


Cc 
Cc 


CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 


CALL GKS$MESSAGE( WS_SCREEN, ‘I just finished printing the house’) 
Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKS$UPDATE_WS( WS_ SCREEN, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


CALL GKSS$DEACTIVATE_WS( WS_PRINTER ) 
CALL GKS$CLOSE_WS( WS_PRINTER ) 

CALL GKS$DEACTIVATE_WS( WS_SCREEN ) 
CALL GKS$CLOSE_WS( WS_SCREEN ) 

CALL GKSS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ These arrays contain the house’s X and Y world coordinates. For exam- 


ple, the first element of the array PX is the X value of the first point, and 
the first element of the array PY is the Y value of the first point (.4, .1). 
This program uses the default world coordinate plane with the starting 
point (0, 0), the maximum X value 1.0, and the maximum Y value 1.0. 


@ The logical name TT defaults to the device connection of your terminal, 


which in this example is a VT241. 


© This code outputs a tall, thin house to the printer. 


The call to the function MESSAGE outputs a message to the VT241 
screen telling the user that the program printed the picture of the house. 


Figure 3-3 shows the screen of a VT241 terminal after the program has run 
to completion. 
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Figure 3-3: Sending the User a Message—VT241 


I just finished printing the house 
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OPEN GKS 


Operating States: GKCL 


Description 


The function OPEN GKS permits subsequent access to the DEC GKS state 
list, DEC GKS description table, and the workstation description tables. 


OPEN GKS changes the DEC GKS operating state from GKS$K_GKCL 
(GKS closed) to GKS$K_GKOP (GKS open). The error state list entry error 
file is set to the value passed as an argument to this function. 


When using DEC GKS, you usually call OPEN GKS first. All functions 
except emergency close, error handling, error logging, OPEN GKS, and 
INQUIRE OPERATING STATE VALUE require at least the GKS$K_GKOP 
operating state. 


Syntax 

GKS$OPEN_GKS (error_file, [, memory]) 

GOPKS (err_file, [, buffer) 

gopengks (errfile, memory) 
Arguments 

error_file 

data type: string 

access: read-only 

mechanism: by descriptor 


This argument is either a logical name or a physical name of a device or file 
that points to the error log file. For information on how GKS handles errors, 
refer to Chapter 10, Error-Handling Functions. 
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NOTE 


If you pass the value 0, DEC GKS uses the translation of the 
logical name SYS$ERROR as the error file. 


memory 


data type: 
access: 


mechanism: 


integer 
read-only 
by reference 


To maintain compatibility with the GKS standard, OPEN GKS accepts an 
optional second argument to indicate the amount of memory units available 
for use by DEC GKS. If provided, DEC GKS ignores this argument. 


Error Messages 


Error 
Number 


200 
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Completion 
Status Code 


DECGKS$_ERROR_NEG_20 
DECGKS$_ERROR_NEG_39 


DECGKS$_ERROR_NEG_97 


DECGKS$_ERROR_NEG_98 


GKS$_ERROR_1 


GKS$_ERROR_200 


Message 


GKS not in proper state: GKS in 
the ERROR state in routine **** 


Descriptor is not acceptable in 
routine **** 

Internal GKS error: Insufficient 
buffer size for translated logical 
name in routine **** 

Internal GKS error: Too many 
translations of logical name in 
routine **** 
GKS not in proper state: GKS 
shall be in the state GKCL in 
routine **** 

Specified error file is invalid in 
routine **** 


OPEN GKS 


Program Example 


Refer to Example 3-1 in this section for a program example using a call to 
OPEN GKS. 
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OPEN WORKSTATION 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function OPEN WORKSTATION initializes a workstation for use by 
DEC GKS, permitting subsequent access to the specified workstation’s state 
list. The function associates the workstation identifier with a particular 
device of a specified type, and initializes the workstation. 


If establishing the first open workstation, OPEN WORKSTATION changes 
the DEC GKS operating state from GKS$K_GKOP (GKS open) to GKS$K_ 
WSOP (at least one workstation open). 


OPEN WORKSTATION clears the display surface of previously generated 
images. You must call this function, followed by a call to ACTIVATE 
WORKSTATION, before you attempt to generate output to this workstation. 


Syntax 


GKS$OPEN_WS _ (workstation_id, device_connection_id, 
workstation_type) 
GOPWK = (workstation_id, con_id, workstation_type) 


gopenws_§ (workstation_id, conid, workstation_type) 
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Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that identifies an open workstation. You 
choose whichever nonnegative integer value your application requires. 


device_connection_id 


data type: string 
access: read-only 
mechanism: by descriptor 


This argument is the device connection identifier that is associated with 
a particular device attached to the host system. This argument can be a 
logical name, a DEC GKS constant value, or a VMS file specification. 


As an option, you can pass either the DEC GKS constant GKS$K_CONID_ 
DEFAULT, or the value 0, by reference. (If you use VAX BASIC, you can 
pass a null string, by reference.) If you use this option, DEC GKS translates 
the logical name GKS$CONID and uses the translation as the name of 

the device. This feature aids program flexibility; each time you execute 
your program, you can use the DIGITAL Command Language commands 
DEFINE or ASSIGN to define GKS$CONID to be the device connection of 
your choice. For more information, refer to Chapter 1, Introduction to DEC 
GKS. 


If the translation of GKS$CONID is not valid, DEC GKS uses the logical 
name TT as the device. The logical name TT is equivalent to your default 
terminal connection. 


Using certain output-only workstation types, you can specify a file name for 
this argument. When you specify a file name, DEC GKS places the graphical 
information into the specified file in the current (or specified) directory. You 
can then print or type the file on the workstation. If you omit the file 
extension, DEC GKS uses the default extension .LIS. Otherwise, DEC GKS 
uses the file name as specified. To determine whether your workstation 
supports an output-only workstation type that would allow you to specify a 
file name for this argument, refer to the DEC GKS Device Specifics Reference 
Manual. 
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NOTE 


If you use OPEN WORKSTATION to create or to read a metafile, 
DEC GKS uses file names for this argument exactly as specified, 
without applying a default extension. For more information 
concerning metafiles, refer to Chapter 9, Metafile Functions. 


workstation_type 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that specifies the workstation type. To 
review the list of possible workstation type values, refer to Appendix A, 
DEC GKS Supported Workstations. For more information concerning valid 
workstation type bitmasks for a given device, refer to the appropriate DEC 
GKS Device Specifics Reference Manual. 


As an option, you can pass either the GKS constant GKS$K_WSTYPE_ 
DEFAULT, or the value 0, by reference. If you use this option, GKS 
translates the logical name GKS$WSTYPE and uses the translation as 

the name of the workstation type. This feature aids program flexibility; 
each time you execute your program, you can use the DIGITAL Command 
Language commands DEFINE or ASSIGN to define GKS$WSTYPE to be the 
workstation type of your choice. For more information, refer to Chapter 1, 
Introduction to DEC GKS. 


If GKS$WSTYPE translates to the value 0, DEC GKS sets the default 
workstation type to GKS$K_VT240BW (on a large VAX) or to GKS$K_VSII 
(on a VAXstation). 
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Error Messages 


Error 
Number 


-30 


—31 


39 


—97 


20 
21 


22 


Completion 
Status Code 
DECGKS$_ERROR_NEG_20 


DECGKS$_ERROR_NEG_30 


DECGKS$_ERROR_NEG_31 


DECGKS$_ERROR_NEG_35 


DECGKS$_ERROR_NEG_39 


DECGKS$_ERROR_NEG_97 


DECGKS$_ERROR_NEG_98 


GKS$_ERROR_8 


GKS$_ERROR_20 


GKS$_ERROR_21 


GKS$_ERROR_22 


OPEN WORKSTATION 


Message 


GKS not in proper state: GKS in 
the ERROR state in routine **** 


Cannot load workstation handler: 
error during image activation in 
routine **** 


Cannot load graphics handler: 
invalid DFT in routine **** 


Kernel has detected an unexpected 
error from a graphics handler in 
routine **** 


Descriptor is not acceptable in 
routine **** 


Internal GKS error: Insufficient 
buffer size for translated logical 
name in routine **** 


Internal GKS error: Too many 
translations of logical name in 
routine **** 


GKS not in proper state: GKS 
shall be in one of the states GKOP, 
WSOP, WSAC or SGOP in routine 


ah 
Specified workstation identifier is 
invalid in routine **** 


Specified connection identifier is 
invalid in routine **** 


Specified workstation type is 
invalid in routine **** 
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Error 
Number 


23 


24 


26 


28 


42 


Program Example 


Completion 
Status Code 


GKS$_ERROR_23 
GKS$_ERROR_24 
GKS$_ERROR_26 


GKS$_ERROR_28 


GKS$_ERROR_42 


Message 


Specified workstation type does 
not exist in routine **** 


Specified workstation is open in 
routine **** 


Specified workstation cannot be 
opened in routine **** 


Workstation Independent Segment 


Storage is already open in routine 
aK 


Maximum number of simultane- 
ously open workstations would be 
exceeded in routine **** 


Refer to Example 3-1 in this section for a program example using a call to 
OPEN WORKSTATION. 
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REDRAW ALL SEGMENTS ON WORKSTATION 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function REDRAW ALL SEGMENTS ON WORKSTATION clears the 
screen and redraws all defined, visible segments. The function performs the 
following tasks in order: 


1. Generates all deferred output (see SET DEFERRAL STATE in this 
section). 


2. If the display surface empty workstation state list entry is GKS$K_ 
NOTEMPTY, this function clears the surface. 


3. Places into effect pending workstation transformations. 


4. Redisplays all visible segments that existed on the workstation surface 
before the screen was cleared. All output not contained in segments is 
lost. 


After executing this function, DEC GKS sets the workstation transformation 
update state entry to GKS$K_NOTPENDING, and the new frame necessary 
at update state list entry to GKS$K_NEWFRAME_NOTNECESSARY. 


NOTE 


You should use this function if you need to redraw the picture 
regardless of the status of the new frame necessary at update 
entry. Otherwise, use UPDATE WORKSTATION. 


GKS$REDRAW_SEG_ON_WS._ (workstation_id) 
GRSGWK_ = (workstation_id) 
gredrawsegws _ (workstation_id) 
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Arguments 


workstation_id 


data type: 
access: 


mechanism: 


integer 
read-only 
by reference 


This argument is an integer value that identifies an open workstation (refer 


to OPEN WORKSTATION in this chapter). 


Error Messages 


20 
25 
33 
35 


36 
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Completion 
Status Code 


DECGKS$_ERROR_NEG 20° 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_33 
GKS$_ERROR_35 


GKS$_ERROR_36 


Message 


GKS not in proper state: GKS in 
the ERROR state in routine **** 


GKS not in proper state: GKS 


shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 

Specified workstation is not open 
in routine **** 

Specified workstation is of cate- 
gory MI in routine **** 

Specified workstation is of cate- 
gory INPUT in routine **** 
Specified workstation is 


Workstation Independent Storage 
in routine **** 


Program 


REDRAW ALL SEGMENTS ON WORKSTATION 


Example 


Example 3-4 illustrates the use of the function REDRAW ALL SEGMENTS 
ON WORKSTATION. Following the program example, Figure 3—4 illustrates 
the program’s effect on a VT241 workstation. 


Example 3-4: Redrawing Segments 


Cc This program creates a segment and then calls 
Cc GKSSREDRAW_SEG ON_WS. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, NUM POINTS, TRIANGLE 
REAL PX( 4 ), PY( 4 ), LARGER 
DATA WS_ID / 1 /, NUM_POINTS / 4 /, TRIANGLE / 1 /, 
* LARGER / 0.02 / 


DATA PX /.1, .9, .1, .1 / 
DATA PY /.1, .9, .9, .1 / 
CALL GKS$OPEN_GKS( ‘'SYSSERROR:’ ) 
CALL GKSS$OPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSS$ACTIVATE_WS( WS_ID ) 
Cc Set the current bundle index to 1. 
CALL GKS$SET_PLINE_INDEX( PLINE_INDEX ) 
CALL GKSSCREATE_SEG( TRIANGLE ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 
CALL GKSSCLOSE_SEG( ) 
Cc Make the text easier to see and then generate the string. 
CALL GKSSSET_TEXT_HEIGHT( LARGER ) 
CALL GKSSTEXT( 0.1, 0.3, 
* “THIS IS NOT PART OF THE SEGMENT’ ) 
Cc Release deferred output. Pause. Type RETURN when you are finished 
C viewing the picture. 
CALL GKS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 
READ (5, *) 
CALL GKSSREDRAW_SEG ON_WS( WS_ID ) 





(continued on next page) 
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Example 3—4 (Cont.): Redrawing Segments 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ These arrays contain the polygon’s X and Y world coordinates. For 
example, the first element of array PX is the X value of the first point 
and the first element of array PY is the Y value. The first point of the 
polygon is (.1, .1). 

@ This code creates a segment that contains a triangle. The code also 
generates a text string to the screen that is independent of the segment. 


© The call to REDRAW ALL SEGMENTS ON WORKSTATION redraws 
the triangle, but does not redraw the text string since the string is not 
part of a segment. 


Figure 3—4 shows the screen of the VT241 terminal after the program has 
run to completion. 
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Figure 3-4: Redrawing Segments—VT241 
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SET DEFERRAL STATE 


Operating States: WSOP, WSAC, SGOP 
Description 


The function SET DEFERRAL STATE sets the workstation state list entries 
deferral mode and implicit regeneration mode. Using this function, you can 
allow a workstation to defer output, or you can either suppress or allow 
implicit regenerations (see Section 3.2.1 for detailed information). 


The deferral mode specifies the rate of output generation. Depending on the 
capabilities of the workstation, it can defer output at any level up to the 
level specified in the call to SET DEFERRAL STATE. If the workstation can 
defer output at the requested level, it does. If the workstation cannot defer 
output at the requested level, it defers output at the next supported lower 
level. 


For example, if you specify GKS$K_ASAP in a call to SET DEFERRAL 
STATE, the workstation must generate output as soon as possible. If 
you specify GKS$K_BNIG, the workstation can defer output at either 
GKS$K_ASAP or GKS$K_BNIG, depending on its capabilities. If you 
specify GKS$K_BNIL, the workstation can defer output on any level up > 
to and including GKS$K_BNIL, depending on its capabilities. If you 
specify GKS$K_ASTI, the workstation can defer output at any of the four 
levels, depending on its capabilities. (For more information concerning 
the definitions of the constants discussed in this paragraph, refer to the 
deferral_mode argument description.) 


The implicit regeneration mode determines whether implicit regenerations 
are allowed (GKS$K_IRG_ALLOWED) or suppressed (GKS$K_IRG_ 
SUPPRESSED). If you allow implicit regenerations, any pending or 
subsequent surface change requiring regeneration (possibly output bundle 
index changes, segment attribute changes, or workstation transformation 
changes) occurs at the time of request. If you suppress regenerations, 
changes requiring regenerations place the screen out of date (DEC GKS 
sets the new frame necessary at update entry in the workstation state list to 
GKS$K_NEWFRAME_NECESSARY). 
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By suppressing implicit regenerations, you can make all necessary changes 
without altering the workstation surface. Then, when you have requested 
all changes, call UPDATE WORKSTATION to perform all the suppressed 
actions in a single regeneration of the surface. 


NOTE 


When regenerating the surface of the workstation, DEC GKS 
clears the surface before redrawing only the visible segments. All 
output primitives not contained in segments are lost. 


Syntax 

GKS$SET_DEFER_STATE (workstation_id, deferral_mode, 

regeneration_mode) 

GSDS_(workstation_id, def_mode, reg_mode) 

gsetdeferst (workstation_id, defmode, irgmode) 
Arguments 

workstation_id 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in this chapter). 


deferral_mode 


data type: integer 
access: read-only 
mechanism: by reference 


This argument specifies the maximum allowable deferral mode. The device 
implements the highest supported mode up to, and including, this specified 
mode. The argument can be any of the following values or constants. _ 
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Value Constant Description 

0 GKS$K_ASAP Generate images as soon as possible. 

1 GKS$K_BNIG Generate images before the next interaction globally 
(before you request input from any open workstation). 

2 GKS$K_BNIL Generate images before the next interaction locally 
(before the next call for input from the specified work- 
station). 

3 GKS$K_ASTI Generate images at some time. The exact time is 


determined by the workstation. 


regeneration_mode 


data type: integer 
access: read-only 
mechanism: by reference 


This argument specifies the implicit regeneration mode. The argument can 
be any of the following values or constants: 


Value Constant Description 


0 GKS$K_IRG_SUPPRESSED Image regeneration is suppressed. 
1 GKS$K_IRG_ALLOWED Image regeneration is allowed. 


Be aware that if you call SET DEFERRAL STATE and pass GKS$K_IRG_ 
ALLOWED, you force the device to implicitly regenerate the surface at 
the time of the function call. When DEC GKS implicitly regenerates a 
workstation surface, it clears the surface and redraws all visible segments 
stored on that workstation. You lose any output primitives not stored in 
segments. 
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Error Messages 


Error 
Number 


20 
25 
33 
35 


36 


Completion 
Status Code 


DECGKS$_ERROR_NEG_20 
DECGKS$_ERROR_NEG_26 
DECGKS$_ERROR_NEG_27 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_33 
GKS$_ERROR_35 


GKS$_ERROR_36 


Program Example 


SET DEFERRAL STATE 


Message 


GKS not in proper state: GKS in 
the ERROR state in routine **** 


Invalid value specified for deferral 
mode in routine **** 


Invalid value specified for regenera- 
tion mode in routine **** 


GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 

Specified workstation is not open in 
routine **** 

Specified workstation is of category 
MI in routine **** 


Specified workstation is of category 
INPUT in routine **** 


Specified workstation is Workstation 
Independent Storage in routine **** 


Example 3—5 illustrates the use of the function, SET DEFERRAL STATE. 
Following the program example, Figure 3—5 illustrates the program’s effect 
on a VT241 workstation. 
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Example 3-5: Suppressing Implicit Regeneration 





This program changes the color of a triangle from 

the default color green, to yellow. Then, the line 

changes from solid to dashed, and from yellow to blue. 
IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, GREEN, NUM_POINTS, NUM_FLAGS, INCR, 

* PLINE_INDEX, TRIANGLE, BLUE 

REAL PX( 4 ), PY( 4 ), LARGER, RED_INTENS, 

* GREEN_INTENS, BLUE_INTENS 

DATA WS_ID / 1 /, NUM_FLAGS / 13 /, GREEN / 1 /, NUM_POINTS / 4 /, 
* RED_INTENS / 1.0000 /, GREEN_INTENS / 1.0000 /, BLUE / 3 /, 
* BLUE_INTENS / 0.4200 /, PLINE_INDEX / 1 /, LARGER / 1.0 /, 
* TRIANGLE / 1 / 

INTEGER FLAGS( 13°) 

0 DATA PX /.1, .9, .1, .1 / 

DATA Py /.1, .9, .9, .1 / 


Qanoa 


CALL GKSSOPEN_GKS( '’SYS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE WS( WS_ID ) 


e CALL GKS$SET_DEFER STATE( WS_ID, GKS$K_ASTI, 
* GKS$K_IRG SUPPRESSED ) 

13) DO 100 INCR = 1, NUM FLAGS, 1 
FLAGS( INCR ) = GKS$K_ASF BUNDLED 


100 CONTINUE 
CALL GKSS$SET_ASF( FLAGS ) 


4) CALL GKSS$CREATE_SEG( TRIANGLE ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG( ) 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 
CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE FLAG ) 
READ (5, *) 
5] CALL GKS$SET_COLOR_REP( WS_ID, GREEN, 
* RED INTENS, GREEN_INTENS, BLUE_INTENS ) 
Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 
CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 
READ (5, *) 


(continued on next page) 
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Example 3-5 (Cont.): Suppressing Implicit Regeneration 


CALL GKS$SET_PLINE_REP( WS ID, PLINE_INDEX, 
* GKS$K_LINETYPE_DASHED, LARGER, BLUE ) 


CALL GKS$UPDATE_WS( WS_ID, GKS$K_PERFORM_ FLAG ) 


CALL GKS$DEACTIVATE _WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


These arrays contain the polygon’s X and Y world coordinates. For 
example, the first element of array PX is the X value of the first point 
and the first element of array PY is the Y value. The first point of the 
polygon is (.1, .1). 


The call to SET DEFERRAL STATE defers output and it suppresses all 
implicit regenerations. 

This code initializes the array that designates attributes as either 
bundled or individually specified. The DO loop initializes all thirteen 
members of the array with the constant GKS$K_ASF_BUNDLED. The 
variable incr increments the array; the variable num_/flags contains the 
number of elements in the array (13). 


For more information, refer to SET ASPECT SOURCE FLAGS in 
Chapter 5, Output Attribute Functions. 


This code places the triangle in a segment. 


This code changes the color representation from green to yellow. 
Changing the color representation of a color index value does not ne- 
cessitate an implicit regeneration on a VT241; the change happens on 
the surface immediately. 

Notice that DEC GKS suppresses the change to the polyline represen- 
tation since, on a VT241, changing the polyline requires an implicit 
regeneration (which is suppressed through the call to SET DEFERRAL 
STATE). 
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@ Once you call UPDATE WORKSTATION and pass the argument 
GKS$K_PERFORM_FLAG, DEC GKS clears the surface and regenerates 
the segment with the new bundled polyline attributes. 


Figure 3—5 shows the screen of the VT241 terminal after the program has 
run to completion. 


Figure 3-5: Suppressing Implicit Regeneration—VT241 
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UPDATE WORKSTATION 


Operating States: WSOP, WSAC, SGOP 


Description 


The function UPDATE WORKSTATION generates all deferred output for 
the specified workstation without first clearing the screen. Then, if the new 
frame necessary at update entry in the workstation state list is GKS$K_ 
NEWFRAME_NECESSARY, and if you specify GKS$K_PERFORM_FLAG 
to this function, UPDATE WORKSTATION performs the following tasks in 
order: 


1. Clears the screen if the display surface empty entry in the workstation 
state list is GKS$K_NOTEMPTY. 


2. Places into effect pending workstation transformations. 


3. Redisplays all visible segments that were stored on the workstation. All 
output primitives not contained in segments are lost. 


After executing the actions listed previously, DEC GKS sets the dis- 

play surface empty workstation state list entry to GKS$K_EMPTY or to 
GKS$K_NOTEMPTY according to the current state of the workstation 
surface, the workstation transformation update state entry to GKS$K_ 
NOTPENDING, and the new frame necessary at update state list entry to 
GKS$K_NEWFRAME_NOTNECESSARY. The deferral and regeneration 
mode entries in the workstation state list have the same values as Mey did 
before the call to UPDATE WORKSTATION. 


However, if at the call to UPDATE WORKSTATION the new frame necessary 
at update entry in the workstation state list is GKS$K_NEWFRAME_ . 
NOTNECESSARY, or if you specify GKS$K_POSTPONE_FLAG as an 
argument to this function, UPDATE WORKSTATION initiates only the 
transmission of any deferred output and will continue to suppress implicit 
regenerations. Again, the deferral mode and regeneration mode entries in 
the workstation state list have the same values as they did before the call to 
UPDATE WORKSTATION. 
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Syntax 
GKS$UPDATE_WS_ (workstation_id, flag) 
GUWK_ (workstation_id, reg_flag) 
gupdatews (workstation_id, regenflag) 
Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in this chapter). 


flag 

data type: integer 
access: read-only 
mechanism: by reference 


This argument establishes the implicit regeneration mode. The argument 
can be any of the following values or constants: 


Value Constant Description 


0 GKS$K_POSTPONE_FLAG Suppress regeneration of images. 
1 GKS$K_PERFORM_FLAG Perform regeneration. 
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Error Messages 


Error 
Number 


20 
25 
33 
35 


36 


Program Example 


Completion 
Status Code 
DECGKS$_ERROR_NEG_20 
DECGKS$_ERROR_NEG_25 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_33 
GKS$_ERROR_35 


GKS$_ERROR_36 


UPDATE WORKSTATION 


Message 


GKS not in proper state: GKS in 
the ERROR state in routine **** 
Invalid value specified for update 
workstation flag in routine **** 
GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 
Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 

Specified workstation is of cate- 
gory MI in routine **** 


Specified workstation is of cate- 
gory INPUT in routine **** 


Specified workstation is 
Workstation Independent Storage 
in routine **** 


For a program example using a call to UPDATE WORKSTATION, refer to 
Example 3-5 in this section. 


For an example of this function updating a workstation surface after 
a change to a workstation viewport and window, refer to Chapter 6, 
Transformation Functions. 
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Chapter 4 


Output Functions 


The DEC GKS output functions generate the basic components, or 
primitives, of all graphical pictures. The output functions are divided into 
the following categories: 


Category GKS Functions 
Draw connected lines. POLYLINE 
Mark locations with symbols. POLYMARKER 
Draw text. TEXT 

Fill a polygon. FILL AREA 
Color cells of a rectangle. CELL ARRAY 


Draw generalized drawing primitive. GENERALIZED DRAWING PRIMITIVE 


(GDP) 


When you generate primitives on the workstation surface, you should be 
aware of the following: 


DEC GKS operating state 

DEC GKS coordinate systems 
Transformations 

Clipping 

Deferred transformations and output 


The following sections describe these issues related to output, and point to 
the appropriate chapters in this manual that discuss the topics in full detail. 
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4.1 Output and the DEC GKS Operating State 


As you call control functions, DEC GKS allows access to certain tables and 
lists. You can never call a DEC GKS function that requires access to a table 
or list that has not yet been made available. To determine which tables and 
lists are accessible, and which DEC GKS functions you can call at a given 
point in the application program, DEC GKS maintains an operating state. 


The DEC GKS operating states are as follows: 


¢ GKS$K_GKCL—DEC GKS is closed. 

¢ GKS$K_GKOP—DEC GKS is open. 

© GKS$K_WSOP—At least one workstation is open. 
¢ GKS$K_WSAC—At least one workstation is active. 
¢ GKS$K_SGOP—A segment is open. 


To call any of the output functions described in this chapter, the DEC GKS 
operating state must be GKS$K_WSAC or GKS$K_SGOP. To place DEC 
GKS into the GKS$K_WSAC operating state, you need to do the following: 


¢ Open DEC GKS (by calling OPEN GKS). 
¢ Open at least one workstation (by calling OPEN WORKSTATION). 
e Activate at least one workstation (by calling ACTIVATE WORKSTATION). 


If you call an output function, DEC GKS generates the primitive on all 
active workstations. If you call an output function during the GKS$K_SGOP 
operating state, then the output primitive becomes part of a segment. (For 
complete information concerning segments, refer to Chapter 8, Segment 
Functions.) 


If you wish to output to an active workstation, the workstation must be 

of type GKS$K_WSCAT_OUTPUT, GKS$K_WSCAT_OUTIN, or GKS$K_ 
WSCAT_MO. Only workstations of those categories support image genera- 
tion. GKS$K_WSCAT_OUTPUT and GKS$K_WSCAT_OUTIN workstations 
generate output primitives on the workstation surface; GKS$K_WSCAT_MO 
workstations store information about the function call in a file. For more 
information concerning metafiles, refer to Chapter 9, Metafile Functions. 
For more information concerning workstation categories or the DEC GKS 
operating states, refer to Chapter 3, Control Functions. 
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4.2 Output Attributes 


All the output primitives have attributes that are stored in the DEC 

- GKS state list. Attributes are properties of the primitive, such as line 
thickness, color, and style. Each attribute has an initial value, provided as a 
default setting. When you call an output function, the current values of its 
attributes are bound to the function, so that the output primitive reflects the 
current attribute values. 


Output attribute functions can radically affect how the output primitive 
appears on the workstation surface. For instance, depending on the current 
text attribute values, the positioning point passed to the output function 
TEXT may be the center point for the text string, the position of the first 
character in the text string, or the position of the last character in the text 
string. The text output attributes also determine whether the string runs 
horizontal to the workstation X axis, vertical to the workstation X axis, or at 
a specified angle on the display surface: . 


This chapter requires that you be familiar with the following attribute 
issues: 


¢ The types of attributes available for a primitive. 

e The effects of using individual and bundled attributes. 
¢ The use of nominal sizes and scale factors. 

e The use of foreground and background color. 


For complete information on these and any other output attribute topics, 
refer to Chapter 5, Output Attribute Functions. 


4.3 Transformations and the DEC GKS Coordinate Systems 


When you input and output primitives, you are actually working with three 
different coordinate systems. These coordinate systems are as follows: 

¢ World coordinate system 

¢ Normalized device coordinate (NDC) system 

¢ Device coordinate system (workstation specific) 

Notice that several program examples in this chapter generate a picture 

of an arrow on the workstation surface. When specifying points in the 


arrow, you use the world coordinate system. The programs pass the world 
coordinate points (0.1, 0.5), (0.9, 0.5), (0.7, 0.6), (0.7, 0.4), and (0.9, 0.5). 
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A world coordinate plane is an imaginary Cartesian coordinate plane, with 
a central point (0, 0), and an X and Y axis that extend to infinity in all 
directions. You establish the limits of the X and Y boundaries within which 
you want to work, and then create the picture you wish to output. All 

the DEC GKS output functions accept the world coordinate points of the 
particular output primitive to be drawn. By default, the primitive must be 
drawn using the coordinate range ([0,1] x [0,1]). (All the program examples 
in this chapter use this default coordinate range.) 


DEC GKS use two separate transformations to translate your world 
coordinates to NDC coordinates, and to translate your NDC coordinates to 
device coordinates. During this process, portions of your primitives may be 
removed from the final picture due to clipping. You need to be aware of the 
effects of transformations and clipping on your generated output primitives. 
For complete information concerning transformations, refer to Chapter 6, 
Transformation Functions. 


4.4 Output Deferral 


When you output primitives, a workstation may postpone the generation 
of the image on the workstation surface depending on the workstation’s 
capabilities. This postponement is called output deferral. 


DEC GKS supports four deferral modes for its supported workstations. The 
deferral modes, in increasing order of deferral, are GKS$K_ASAP (generates 
output as soon as possible), GKS$K_BNIG (generates output before the 
next interaction globally), GKS$K_BNIL (generates output before the next 
interaction locally), and GKS$K_ASTI (at some time). 


You can specify a suggested level of deferral by calling the function SET 
DEFERRAL STATE. Depending on the capabilities of the workstation, it can 
defer output at the highest level up to the level specified in the call to SET 
DEFERRAL STATE. 


For detailed information concerning SET DEFERRAL STATE and deferral, 
refer to Chapter 3, Control Functions. 
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4.5 Output Inquiries 


The following list presents the inquiry functions that you can use to obtain 
output information when writing device-independent code: 


INQUIRE LIST OF AVAILABLE GENERALIZED DRAWING 
PRIMITIVES 

INQUIRE PIXEL ARRAY 

INQUIRE SET OF ACTIVE WORKSTATIONS 

INQUIRE PIXEL ARRAY DIMENSIONS 

INQUIRE GENERALIZED DRAWING PRIMITIVE 

INQUIRE OPERATING STATE 

INQUIRE PIXEL 

INQUIRE TEXT EXTENT 


For more information concerning device-independent programming, refer to 
the DEC GKS User Manual. 


4.6 DEC GKS Output Function Descriptions 


This section describes the DEC GKS output functions in detail. 
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CELL ARRAY 


Operating States: WSAC, SGOP 


Description 


Syntax 


The function CELL ARRAY divides a designated rectangular area into cells, 
and displays each cell in a specific color or shade. 


You pass a two-dimensional array containing color index values as one 
argument to this function. CELL ARRAY maps the color index values to 
corresponding cells within a rectangular area of the workstation surface. In 
addition to the color index array, you specify an offset into the color array 
(a starting element), the number of array columns to be mapped, and the 
number of array rows to be mapped. 


There is a one-to-one correspondence between the number of specified array 
columns and rows, and the number of columns and rows by which DEC GKS 
divides the cell array rectangle. Each of the columns within the rectangle is 
of equal width, and each of the rows within the rectangle is of equal height. 
DEC GKS maps the color index values from each specified color index array 
element to the corresponding cell, moving from the starting point towards 
the diagonal point along the X axis. 


For more information concerning the initial color index values for a given 
workstation, refer to the DEC GKS Device Specifics Reference Manual. To 
alter the color associated with a certain index value, you can use the GKS 
function SET COLOR REPRESENTATION (refer to Chapter 5, Output 
Attribute Functions). 


GKS$CELL_ARRAY (siarting_point_x, starting_point_y, 
diagonal_point_x, diagonal_point_y, 
offset_column_number, offset_row_number, 
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number_of_columns, number_of_rows, 
color_index_value) 


GCA (spx, spy, dpx, dpy, dim_x, dim_y, scol, srow, ncols, nrows, 
cindex) 


gcellarray (rectangle, dimensions, colour) 


Arguments 


starting_point_x 
starting _point_y 


data type: real 
access: read-only 
mechanism: by reference 


These arguments designate any corner of the cell array rectangle as the cell 
array starting point. You pass these arguments as world coordinate values. 


diagonal_point_x 
diagonal_point_y 


data type: real 
access: read-only 
mechanism: by reference 


These arguments specify the corner of the cell array that is diagonal to the 
starting point, in world coordinates. 


offset_column_number 
offset_row_number 


data type: integer 
access: read-only 
mechanism: by reference 


These arguments are the offset into the color index array: The offset 
determines the number of array columns and rows that you specify as 
arguments to CELL ARRAY. For instance, if the offset is the first element of 
the array, you can specify the full dimensions of the color index array as the 
“number of columns to map” and the “number of rows to map.” 
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If you specify an offset that begins mapping in the interior of the color index 
array, you can only specify the remaining columns and rows as the number 
of columns and rows to map. For instance, if you pass an array three 
columns by four rows and specify an offset at element (2, 2), DEC GKS can 
only map the indexes from the two columns and three rows that follow the 
offset array element: elements (2, 2), (3, 2), (2, 3), (8, 3), (2, 4), (3, 4). If 
you attempt to divide the rectangle into more columns and rows than those 
from the offset to the last element in the array, DEC GKS generates an 
error. 


Example 4—1 reproduces the situation described in the last paragraph. 


number_of_columns 
number_of_rows 


data type: integer 
access: read-only 
mechanism: by reference 


These arguments specify into how many columns and rows DEC GKS 
divides the cell array rectangle. If you attempt to divide the rectangle 
into more columns and rows than those from the offset element to the 
last element of the color index array, DEC GKS generates an error. For 
more information, refer to the previous argument descriptions and to 
Example 4-1. 


color_index_value 


data type: 2-D array (integer) 
access: read-only 
mechanism: by descriptor 


This argument is the two-dimensional array that contains the color index 
values. Previous arguments determine the offset element, the number of 
array columns to traverse, and the number of array rows to traverse. 


When DEC GKS maps the values from the color index array to the cell 
array, it starts at the corner cell containing the cell array starting point and 
maps towards the diagonal point along the X axis. DEC GKS divides the 
cell array rectangle into the number of cells equal to the number of array 
elements specified by the previous arguments. Each cell is equal in width, 
and each cell is equal in height. 
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For more information on the color index array, refer to Example 4-1. 


NOTE 


The CELL ARRAY example uses a FORTRAN column-major color 
index array. You may produce a different cell array if you use a 
language that supports row-major arrays (such as Pascal, C, and 


so forth). 


Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
-33 DECGKS$_ERROR_NEG_33 
5 GKS$_ERROR_5 

91 GKS$_ERROR_91 


Program Example 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


Array descriptor is not acceptable 
in routine **** 


GKS not in proper state: GKS 
shall be either in the state WSAC 


or in the state SGOP in routine 
RK 


Dimensions of color array are 
invalid in routine **** 


Example 4—1 illustrates the use of the function CELL ARRAY. Following the 
program example, Figures 4-3, 4—4, and 4-5 illustrate the program’s effect 


on a VT241 workstation. 


Output Functions 4-9 


CELL ARRAY 


Example 4—1: Cell Array Output 


Cc This program displays three cell array rectangles. 

IMPLICIT NONE 
INCLUDE '’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER COLORS( 3, 4 ), NUM_COLS, NUM_ROWS, START COL, 
* START ROW, WS_ID 
REAL START X, START_Y, DIAG X, DIAG Y 

1) DATA COLORS /3,2,0, 1,3,2, 0,2,0, 3,1,1/ 
DATA WS_ID / 1 / 


CALL GKS$OPEN GKS( 'SYS$ERROR:’ ) 
CALL GKSSOPEN WS( WS_ID, GKS$K_CONID_ DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE WS( WS_ID ) 


START_X 
START Y 
DIAG X 
DIAG Y 


I 
ooo°o 
roOwor 


START_ROW 
START COL = 
NUM_COLS = 
NUM_ROWS = 


Il 
PR 


fl 
mW 


@ CALL GKS$CELL_ARRAY(START_X, START _Y, DIAG_X, DIAG _Y, 
* START COL, START ROW, NUM_COLS, NUM_ROWS, %DESCR( COLORS )) 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the screen. 

CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


I 


START_X 
START_Y 
DIAG X 
DIAG Y 


Nl 
oo0°0 
rFoOUOF 


START _ROW = 
START COL = 
NUM_COLS = 2 
NUM_ROWS = 3 


NS 





(continued on next page) 
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Example 4-1 (Cont.): Cell Array Output 


© CALL GKS$CELL_ ARRAY (START X, START Y, DIAG X, DIAG Y, 
* START COL, START ROW, NUM_COLS, NUM_ROWS, %DESCR( COLORS )) 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the screen. 
CALL GKSSUPDATE WS( WS_ID, GKS$K_POSTPONE FLAG ) 
READ (5, *) 
START_X = 0.1 
START Y = 0.1 
DIAG X = 0.9 
DIAG Y = 0.9 
START _ROW = 2 
START COL = 2 
NUM_COLS = 2 
NUM_ROWS = 3 
4 ) CALL GKS$CELL_ ARRAY (START_X, START_Y, DIAG X, DIAG Y, 


* START COL, START ROW, NUM_COLS, NUM_ROWS, %DESCR( COLORS )) 


CALL GKSSDEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS() 

END 


The following numbers correspond to the numbers in the previous example: 


@ This code initializes the variable colors with three columns and four 
rows of color index values. By default, the index number 0 specifies 
black; the index number 1 specifies green; the index number 2 specifies 
red, and the index number 3 specifies blue. This program uses the same 
color index array as the one pictured in Figure 4-1. 


@ This code creates a rectangle whose starting corner point is (.1, .9) 
in world coordinates and whose diagonal corner point is (.9, .1) in 
world coordinates. DEC GKS divides the cell array rectangle into three 
columns of four rows. 
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CELL ARRAY 


CELL ARRAY uses the color index value in the first column and in the 
first row of the array colors. CELL ARRAY assigns one color to one cell 
until it colors all three columns and all four rows. After this call, the 
upper left cell array is blue, the next cell to the right is red, the last cell 
in that row is black, and so forth. To compare the contents of the color 
index array with the cell array on the screen, compare Figure 4—1 with 
Figure 4-3. 


You use the FORTRAN argument list built-in function 2DESCR() to 
pass an array by descriptor. 


© In this call to CELL ARRAY, the offset array element is now (2, 2). 
This call divides the rectangle into the maximum allowable columns 
(2) and rows (3) given the location of the offset element. To compare 
the contents of the color index array with the cell array on the screen, 
compare Figure 4-2 with Figure 44. 


© In this call to CELL ARRAY, the starting corner point is the lower left 
corner. DEC GKS divides the cell along the X axis from the starting 
corner point cell to the diagonal point cell. Notice how the cell array 
appears to be a mirror image of the other cell array generated by this 
program. To compare the contents of the color index array with the cell 
array on the screen, compare Figure 4—2 with Figure 4—5. 
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Figure 4-1: The Maximum Number of Cells in the Cell Array 





FORTRAN Color Index Array Representation 
(A Column-Major Array) 


1 2 3 e « « # columns 


Offset 
Row 


Map at most 
3 rows 





Map at most 
2 Columns 
Offset Column 
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Figure 4-2: Possible Mapping Directions Using the Cell Array 


VAX GKS maps from the starting point toward 
the diagonal point, always along the X axis. 


mapping direction mapping direction 





mapping direction mapping direction 


By changing the starting and diagonal 
points, you can choose between four 


different mirror images. 
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Figure 4-3: Cell Array Output—VT241 
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Figure 4—4: The Second Call for Cell Array Output—VT241 
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Figure 4-5: The Third Call for Cell Array Output—VT241 
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FILL AREA 


Operating States: WSAC, SGOP 


Description 


The function FILL AREA. draws a polygon and fills it with an interior style. 


The fill area interior style can be either hollow, solid, hatched, or pat- 
terned. For instance, the default fill area interior style for most supported 
workstation types is hollow (FILL AREA draws the outline of the polygon, 
leaving the interior hollow). For information on how to change the fill area 
attributes, refer to Chapter 5, Output Attribute Functions. 


Syntax 
GKS$FILL_AREA (number_of_points, x_coordinates, 
y_coordinates) 
GFA (number_of_points, px, py) 
gfillarea (number_of_points, points) 
Arguments 
number_of_points 
data type: integer 
access: read-only 
mechanism: by reference 


This argument specifies the number of points in the polygon. 
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X_coordinates 
y_coordinates 


data type: array (real) 
access: read-only 
mechanism: by reference 


These arguments are arrays containing the X and the Y values of the 
polygon’s world coordinate points. The number of array elements should 
match the value of number_of_points. 


You do not have to specify a closed polygon. If you do not specify a closed 
polygon, DEC GKS connects the last point specified to the first point. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

5 GKS$_ERROR_5 ’  GKS not in proper state: GKS 
shall be either in the state WSAC 
or in the state SGOP in routine 
KKK 

100 GKS$_ERROR_100 Number of points is invalid in 


routine **** 


Program Example 
Example 4—2 illustrates the use of the function FILL AREA. Following the 


program example, Figure 4—6 illustrates the program’s effect on a VT241 
workstation. . 
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4-20 


Example 4-2: Fill Area Output 


Cc This 


program splits a rectangle in half and then 


c fills both halves with different interior styles. 
IMPLICIT NONE 
INCLUDE '’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER NUM_POINTS, WS_ID, PURPLE PATTERN 


REAL 


0 DATA 
DATA 
DATA 
DATA 
DATA 


CALL 
CALL 
CALL 


2] CALL 


3] CALL 
CALL 


4) CALL 


CALL 
CALL 
CALL 
END 


PX( 3), PY( 3 ), PX2( 3 ), PY2( 3 ) 


PX /.1, .9, .1/ 
PY /.1, .9, .9/ 
PX2 /.1, .9, .9/ 
PY2 /.1, .1, .9/ 
WS_ID / 1 /, NUM_POINTS / 3 /, PURPLE_PATTERN / 2 / 


GKSS$OPEN_GKS( ‘SYS$ERROR:’ ) 
GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
GKSSACTIVATE WS( WS_ID ) 


GKS$FILL_AREA( NUM POINTS, PX, PY ) 


GKS$SET_FILL INT _STYLE( GKS$K_INTSTYLE PATTERN ) 
GKSS$SET FILL STYLE _INDEX( PURPLE PATTERN ) 


GKSS$FILL_AREA( NUM_POINTS, PX2, PY2 ) 


GKSSDEACTIVATE WS( WS_ID ) 
GKSSCLOSE_WS( WS_ID ) 
GKSSCLOSE_GKS () 


The following numbers correspond to the numbers in the previous example: 


@ These arrays contain the polygon’s X and Y world coordinates. For 
example, the first element of the array PX is the X value of the first 
point, and the first element of the array PY is the Y value. The first 
world coordinate point in the polygon is (.1, .1). 


@ In the call to FILL AREA, you specify that there are three points in the 
polygon, as well as the arrays containing the world coordinate points. 


This code changes the interior fill attribute from hollow to pattern, and 
then specifies the index number of a pattern. On the VT241, the default 
pattern for pattern index value 2 generates a purple pattern. If you are 
not working with a VT241, you may have to specify a different pattern 
index value to achieve the same effects. For more information on SET 
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FILL AREA INTERIOR STYLE and SET FILL AREA STYLE INDEX, 
refer to Chapter 5, Output Attribute Functions. 


@ This code fills the other triangle using the second set of X and Y world 
coordinate values. 


Figure 4—6 shows the screen of a VT241 terminal after the program runs to 
completion. 


Figure 4—6: Fill Area—VT241 
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GENERALIZED DRAWING PRIMITIVE 


Operating States: WSAC, SGOP 


Description 


The function GENERALIZED DRAWING PRIMITIVE generates a gen- 
eralized drawing primitive (GDP) of the type you specify, using given 
points and any additional information contained in a data record. A GDP 
is a device-specific primitive that is not supported as a primitive by GKS. 
For instance, using DEC GKS, you can pass a center world coordinate point 
and a perimeter point to this function, and the specified workstation that 
supports such a GDP draws a circle on the workstation surface. 


The definition of the particular GDP primitive specifies which sets of 
attributes the workstation uses to generate the primitive. For instance, the 
GDPs that generate circles use the set of polyline attributes. 


Depending on the workstation-dependent requirements of the GDP, DEC 

GKS may or may not generate the primitive if certain points fall outside 

the current workstation window. If a workstation cannot generate a GDP 
because points fall outside of the current workstation window, DEC GKS 

generates an error message. 


For complete descriptions of all the DEC GKS supported GDPs, refer to 
Appendix I, DEC GKS GDPs and Escapes. 


Syntax 


GKS$GDP (number_of_points, x_coordinates, y_coordinates, 
gdp_id, data_record, data_record_size) 

GGDP (number_of_points, px, py, gdp_id, dim_dr, dr) 

ggdp (number_of_points, points, function, data) 
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Arguments 
number_of_points 
data type: integer 
access: read-only 
mechanism: by reference 


This argument specifies the number of points in the GDP. 


x_coordinates 
y_coordinates 


data type: array (real) 
access: read-only 
mechanism: ' by reference 


These arguments are arrays containing the X and the Y values of the GDP’s 
world coordinate points. The number of array elements should match the 
value of number_of_points. 


gdp_id 

data type: integer 
access: read-only 
mechanism: by reference 


This argument is the GDP identifier. For a complete list of GDP identifiers, 
refer to Appendix I, DEC GKS GDPs and Escapes. 


data_record 


data type: address (record) 
access: read-only 
mechanism: by reference 


This argument is the address of the GDP data record. For information 
concerning the structure of this data record, refer to Chapter 1, Introduction 
to DEC GKS. For information concerning data record structures required for 
specific GDPs, refer to Appendix I, DEC GKS GDPs and Escapes. 
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data_record_size 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the GDP data record size in bytes. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

5 GKS$_ERROR_5 GKS not in proper state: GKS 
shall be either in the state WSAC 
or in the state SGOP in routine 
hee 

100 GKS$_ERROR_100 Number of points is invalid in 
routine **** 

102 GKS$_ERROR_102 Generalized Drawing Primitive 
identifier is invalid in routine **** 

103 GKS$_ERROR_103 Content of Generalized Drawing 


Primitive data record is invalid in 
routine **** 


104 GKS$_ERROR_104 At least one active workstation is 
not able to generate the specified 
Generalized Drawing Primitive in 
routine **** 


105 GKS$_ERROR_105 At least one active workstation is 

; not able to generate the specified 
Generalized Drawing Primitive 
under the current transformation 
and clipping rectangle in routine 
KR 
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Program Example 


Example 4-3 illustrates the use of the function GDP. Following the 
program example, Figure 4—7 illustrates the program’s effect on a VT241 
workstation. 


Example 4-3: Generalized Drawing Primitive Output 


Cc This program creates a filled circle using the GDP 
Cc GKS$K_GDP_CIRCLE_3PT. 
IMPLICIT NONE 
INCLUDE ’SYSS$LIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, NUM_POINTS, DATA_RECORD( 1 ), RECORD SIZE 


REAL PX( 3 ), PY( 3 ) 


DATA PX / 0.1, 0.5, 0.9 / 
DATA PY 7 025, 021; (0.9: 7 
DATA WS_ID / 1 /, NUM_POINTS / 3 /, RECORD SIZE / 0 / 


CALL GKSSOPEN_GKS( 'SYSS$ERROR:’ ) 

CALL GKS$OPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, 
* GKS$K_VT240 ) 

CALL GKS$ACTIVATE_WS( WS_ID ) 


Cc Pass the identifier of the filled circle. 
CALL GKSSGDP ( NUM_POINTS, PX, PY, 
1) * GKS$K_GDP_CIRCLE_3PT, DATA_RECORD, RECORD SIZE ) 


CALL GKSS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 

CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ The constant GKS$K_GDP_CIRCLE_8PT specifies the GDP identifi- 
cation number —102. This GDP creates a circle using three points on 
the circle’s circumference. This particular GDP does not require a data 
record to perform its task. Notice that DEC GKS uses the current poly- 
line attributes to create the circle. For more information concerning 
available GDPs, refer to Appendix I, DEC GKS GDPs and Escapes. 


Output Functions 4-25 


GENERALIZED DRAWING PRIMITIVE 


Figure 4—7 shows the screen of a VT241 terminal after the program runs to 
completion. 


Figure 4—7: Generalized Drawing Primitive Output—VT241 
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POLYLINE 


Operating States: WSAC, SGOP 


Description 


Syntax 


The function POLYLINE draws one or more straight lines, connecting the 
world coordinate points in the order specified. 


By default, POLYLINE draws line segments as solid lines, at the nominal 
width, in the foreground color. For information on changing the polyline 
attributes, refer to Chapter 5, Output Attribute Functions. 


GKS$POLYLINE (number_of_points, x_coordinates, 
y_coordinates) 


GPL (number_of_points, px, py) 
gpolyline (number_of_points, points) 


Arguments 


number_of_points 


data type: integer 
access: read-only 
mechanism: by reference 


This argument specifies the number of points in the polyline. 
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X_coordinates 
y_coordinates 


data type: - array (real) 
access: read-only 
mechanism: by reference 


These arguments are arrays containing the X and the Y values of the 
polyline’s world coordinate points. The number of array elements should 


match the value of number_of_points. 


Error Messages 


Error Completion 

Number Status Code 

-20 DECGKS$_ERROR_NEG_20 
5 GKS$_ERROR_5 

100 GKS$_ERROR_100 


Program Example 
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Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 


shall be either in the WSAC or in 
the state SGOP in routine **** 


Number of points is invalid in 
routine **** 


Example 4—4 illustrates the use of the function POLYLINE. Following the 
program example, Figure 4-8 illustrates the program’s effect on a VT241 


- workstation. 
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Example 4—4: Polyline Output 





Cc This program draws an arrow. 
IMPLICIT NONE 
INCLUDE 'SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, NUM_POINTS 
REAL PX( 5 ), PY( 5 ) 


DATA PX (237 396 .c0y- 8 ¥9: «9/7 
DATA. PY 55-45) «6p: G4 5/ 
DATA WS_ID / 1 /, NUM_POINTS / 5 / 


CALL GKSSOPEN_GKS( ’SYSSERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE_WS( WS_ID ) 


CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ These arrays contain the X and Y values of the polyline’s world coordi- | 
‘nates. For example, the first element of the array PX is the X value of 
the first point, and the first element of the array PY is the Y value of the 
first point. The first world coordinate point in the polyline is (.1, .5). 


@ In the call to POLYLINE, you specify the number of world coordinate 
points and the array variables. 


Figure 4—8 shows the screen of a VI241 terminal after the program runs to 
completion. 
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Figure 4-8: Polyline Output—VT241 





ZK-5051-86 


4-30 Output Functions 


POLYMARKER 


POLYMARKER 


Operating States: WSAC, SGOP 


Description 


Syntax 


The function POLYMARKER places one or more special symbols called 
markers at the specified world coordinates. 


By default, POLYMARKER produces an asterisk marker, at the nominal 
size, in the workstation-specific default foreground color. For information on 
changing these polymarker attributes, refer to Chapter 5, Output Attribute 
Functions. | 


If clipping is enabled, and if the marker coordinate point is outside of the 


_ clipping rectangle, then DEC GKS clips the entire marker. If clipping is 


enabled, if the marker coordinate point is inside of the clipping rectangle, 
and if portions of the marker exceed the boundaries of the clipping rectangle, 
the extent of the clipping is device dependent. For more information 
concerning clipping, refer to Chapter 6, Transformation Functions. 


GKS$POLYMARKER = (number_of_points, x_coordinates, 
y_coordinates) 


GPM (number_of_points, px, py) 
gpolymarker (number_of_points, points) 
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Arguments 


number_of_points 


data type: integer 
access: read-only 
mechanism: by reference 


This argument specifies the number of marker coordinate locations. 


x_coordinates 
y_coordinates 


data type: array (real) 
access: read-only 
mechanism: by reference 


These arguments are arrays containing the X and the Y values of the 
marker’s world coordinate points. The number of array elements should 
match the value of number_of_poinis. 


Error Messages 


Error Completion 

Number Status Code Message 

-20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

5 GKS$_ERROR_5 GKS not in proper state: GKS 
shall be either in the state WSAC 
or in the state SGOP in routine 
ERE 

100 GKS$_ERROR_100 Number of points is invalid in 


routine **** 


4~32 Output Functions 


POLYMARKER 


Program Example 


Example 4-5 illustrates the use of the function POLYMARKER. Following 
the program example, Figure 4—9 illustrates the program’s effect on a VT241 
workstation. 


Example 4-5: Polymarker Output 


Cc This 


program generates five markers. 


IMPLICIT NONE 
INCLUDE ‘ SYS$LIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, NUM_POINTS 


REAL 


0 DATA 
DATA 
DATA 


2 ] CALL 


CALL 
CALL 
CALL 
END 


PX( 5), PY¥( 5 ) 


BX Ae hy 2 Op alg oe Os 
BY. /25¢. oS: 265 247 2 5/ 
WS_ID / 1 /, NUM_POINTS / 5 / 


GKSS$OPEN_GKS( 'SYS$ERROR:’ ) 
GKSSOPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKSS$K_VT240 ) 
GKSS$ACTIVATE WS( WS_ID ) 


GKSSPOLYMARKER( NUM_POINTS, PX, PY ) 


GKS$DEACTIVATE WS( WS_ID ) 
GKS$CLOSE_WS( WS _ID ) 
GKS$CLOSE_GKS () 


The following numbers correspond to the numbers in the previous example: 


@ These arrays contain the X and Y values of the markers’ world coordi- 
nates. For example, the first element of the array PX is the X value of 
the first marker point, and the first element of the array PY is the Y 
value. The first marker world coordinate point is (.1, .5). 


@ In the call to POLYMARKER, you specify the number of world coordinate 
points to be marked and the array variables. 
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Figure 4-9 shows the screen of a VT241 terminal after the program runs to 
completion. 


Figure 4-9: Polymarker Output—VT241 
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TEXT 


Operating States: WSAC, SGOP 


Description 


Syntax 


The function TEXT writes a character string that DEC GKS positions 
according to the specified world coordinates and according to the current 
text attributes. The shape of the characters within the text string may 
vary depending on the current text attributes, the current normalization 
transformation, and the particular workstation capabilities. 


There are text attributes that control the nongeometric text properties 
(text font and precision, character expansion factor, character spacing, 

and text color index) and the geometric text properties (character height, 
character-up vector, character path, and character alignment). To determine 
the options concerning the appearance of the text string on the workstation 
surface, review the text attribute functions in Chapter 5, Output Attribute 
Functions. 


The amount of the string that DEC GKS clips depends on both the current 
text attributes and the particular workstation capabilities. For string 
precision, DEC GKS clips the string in a workstation-dependent manner. 
For character precision, DEC GKS clips the string character by character. 
For stroke precision, DEC GKS clips the string exactly at the normalization 
viewport. For more information concerning clipping and normalization 
viewports, refer to Chapter 6, Transformation Functions. 


GKS$TEXT (x_coordinate, y_coordinate, text_string) 
GTX (px, py, text) 

GTXS - subset (px, py, /text, text) 

gtext (position, text) 
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Arguments 


x_coordinate 
y_coordinate 


data type: real 
access: read-only 
mechanism: by reference 


These arguments are the world coordinates that position the text string. 


Depending on the current text attributes, DEC GKS positions the first 
character, the last character, or the middle of the text string at this world 
coordinate point. By default, DEC GKS positions the first character in 
the string at this point, and writes subsequent characters to the right of 
the starting point. You should review SET CHARACTER UP VECTOR, 
SET TEXT PATH, and SET TEXT ALIGNMENT to see the options 
concerning placement of the text string on the workstation surface. For 
more information, refer to Chapter 5, Output Attribute Functions. 


text_string 


data type: string 
access: read-only 
mechanism: by descriptor 


This argument is the ASCII text string to be written to the workstation 
surface. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
. the error state in routine **** 

—33 DECGKS$_ERROR_NEG_33 Array descriptor is not acceptable 


in routine **** 
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Program Example 


Completion 
Status Code 


DECGKS$_ERROR_NEG_34 


GKS$_ERROR_5 


GKS$_ERROR_101 


TEXT 


Message 


String length less than or equal to 
0 in routine **** 


GKS not in proper state: GKS 
shall be either in the state WSAC 


or in the state SGOP in routine 
KKK 


Invalid code in string in routine 
eK 


Example 4—6 illustrates the use of the function, TEXT. Following the 
program example, Figure 4—10 illustrates the program’s effect on a VT241 


workstation. 


Example 4-6: Text Output 


Cc This program writes a string to the workstation using the 
C default text attributes. 
IMPLICIT NONE 


INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 


INTEGER WS_ID 

REAL WORLD_X, WORLD_Y, LARGER 
DATA WS_ID / 1 /, WORLD _X / 0.1 /, WORLD_Y / 0.5 /, 
* LARGER / 0.04 / 


CALL GKSSOPEN_GKS( ‘SYS$ERROR:’ ) 


CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKSS$ACTIVATE WS( WS ID ) 


Cc Increase text height by four times for clarity. 


CALL GKS$SET_TEXT_HEIGHT( LARGER ) 


CALL GKSS$TEXT( WORLD_X, WORLD_Y, 
* 'TEXT: 0.04 WC units’ ) 


(continued on next page) 
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Example 4—6 (Cont.): Text Output 


CALL GKS$DEACTIVATE WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


Figure 4-10 shows the screen of a VT241 terminal after the program runs to 
completion. 


Figure 4-10: Text Output—VT241 


TEXT: 09.04 WC units 
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Chapter 5 


Output Attribute Functions 


The DEC GKS output attribute functions affect the appearance of generated 
output primitives. The following list presents the output attribute functions 


by category: 


Category 
Fill Area Attributes 


Polyline Attributes 


Polymarker Attributes 


GKS Functions 


SET FILL AREA COLOR INDEX 
SET FILL AREA INDEX 

SET FILL AREA INTERIOR STYLE 
SET FILL AREA STYLE INDEX 
SET PATTERN REFERENCE POINT 
SET PATTERN SIZE 


SET POLYLINE COLOR INDEX 
SET POLYLINE INDEX 

SET LINETYPE 

SET LINEWIDTH SCALE FACTOR 


SET POLYMARKER COLOR INDEX 
SET POLYMARKER INDEX 

SET MARKER SIZE SCALE FACTOR 
SET MARKER TYPE 
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Category GKS Functions 


~ Text Attributes SET TEXT ALIGNMENT 
SET TEXT COLOR INDEX 
SET CHARACTER EXPANSION FACTOR 
SET TEXT FONT AND PRECISION 
SET CHARACTER HEIGHT 
SET TEXT INDEX 
SET TEXT PATH 
SET CHARACTER SPACING 
SET CHARACTER UP VECTOR 

Aspect Source Flags SET ASPECT SOURCE FLAGS 


Representations SET COLOR REPRESENTATION 
SET FILL AREA REPRESENTATION 
SET PATTERN REPRESENTATION 
SET POLYLINE REPRESENTATION 
SET POLYMARKER REPRESENTATION 
SET TEXT REPRESENTATION 


Pick Attributes SET PICK IDENTIFIER 


The DEC GKS state list stores the current value of the output attributes 
for each output function. These attributes specify the exact appearance of 
the object drawn. For example, when you call POLYLINE, the attributes 
line type, width scale factor, and color specify the form, thickness, and color 
of the line. In the DEC GKS state list, these current attributes are stored 
in the entries current line type, current line width scale factor, and current 
polyline color index. 


When you call a DEC GKS output function, the attributes are bound to 

the primitive. If the primitive’s attributes are individual, then you cannot 
change these attributes; changes to output attributes only affect subsequent 
output. If the primitive’s attributes are bundled, then you may be able to 
change the attributes of previously generated primitives by calling one of 
the representation functions, depending on the capabilities of your device. 
See Section 5.2 for more information concerning individual and bundled 
attributes. 


5.1 Types of Attributes 


Attributes can affect geometric, nongeometric, and pick identification 
aspects of a graphic image. The geometric and nongeometric aspects of a 
graphic image directly affect how the primitive appears on the workstation 
surface. The pick identification is used when performing pick input. For 
complete details concerning pick input, refer to Chapter 7, Input Functions. 


5-2 Output Attribute Functions 


Most output functions have nongeometric attributes that are changeable 
(cell arrays and generalized drawing primitives do not). Nongeometric 
attributes affect the style and the pattern of the output primitives (such 
as polyline color, text spacing, and fill area interior style). Since the 
nongeometric attributes are scale factors and nominal sizes, the effects of 
these attributes are device dependent. 


Nominal sizes are the default sizes of markers and line widths as defined 
by a graphics handler. In most cases the nominal size is also the smallest 
size that a workstation can produce, but not always. DEC GKS multiplies 
the scale factor values by the nominal size to reset a marker size or polyline 
width. The default value for a scale factor is 1.0 (the nominal size multiplied 
by the value 1.0, producing no change in size). 


Geometric attributes affect the size or positioning of text and fill area 
primitives (such as text height, character path, and pattern size). Fill area 
and text are the only two output primitives that have changeable geometric 
attributes. The geometric attributes are specified in world coordinate units. 
Therefore, since the world coordinates are device independent, the geometric 
attributes are device independent. 


Table 5-1 lists the output attributes and whether an attribute is geometric 
or nongeometric. 


Table 5-1: Geometric and Nongeometric Output Attributes 


Function Attribute Type 

Polyline Polyline index Nongeometric 
Line type Nongeometric 
Line width scale factor Nongeometric 
Polyline color index Nongeometric 

Polymarker Polymarker index Nongeometric 
Marker type Nongeometric 
Marker size Nongeometric 
Polymarker color index Nongeometric 


(continued on next page) 
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Table 5-1 (Cont.): 


Function 


Geometric and Nongeometric Output Attributes 


Attribute Type 

Text Text index Nongeometric 
Text height Geometric 
Character up vector Geometric 
Text path Geometric 
Text alignment Geometric 
Text font and precision Nongeometric 
Character expansion factor Nongeometric 
Character spacing Nongeometric 
Text color index Nongeometric 

Fill area Fill area index Nongeometric 
Pattern size Geometric 
Pattern reference point Geometric 
Fill area interior style Nongeometric 
Fill area style index Nongeometric 
Fill area color index Nongeometric 


Notice that there are no attribute functions specifically designed to alter 
the cell array or the generalized drawing primitives (GDPs). A cell array is 
simply an array of indexes that point to the workstation’s color table. 


The GDP has no attributes specifically designed for it. Depending on the 
workstation-specific GDP data record, you may need to specify any number 
of the polyline, polymarker, text, or fill area attribute values, depending on 
the nature of the GDP. 


5.2 Individual and Bundled Attribute Values 


As stated previously, the current values of each attribute are listed 
individually in the DEC GKS state list. By default, a call to an output 
function uses these individual, attribute values to generate the primitive. 
Since DEC GKS stores these individual attributes in the DEC GKS state 
list, they are essentially device independent. If you specify attributes 
individually, you cannot change a primitive’s appearance on the workstation 
surface once you generate it. 


5-4 Output Attribute Functions 


However, there is a second method used to specify attribute values. 

Each workstation can define a number of attribute bundles for an output 
primitive. Each bundle is an entry in a table that contains attribute values 
for each of the nongeometric values of that particular output primitive. 
DEC GKS stores bundle tables in the workstation state lists, thereby 
making the bundle table entries device dependent. You specify bundle table 
entries by specifying a bundle index value that points into the table. Most 
workstations provide a fill area bundle index 1, but the resulting fill area 
can look different on each workstation. 


For example, a polyline bundle contains table entries for polyline index, line 
type, line width scale factor, and polyline color index. A workstation can 
define a bundle table entry with the index 1 that specifies a solid line type. 
The same workstation can define another bundle table entry with the index 
2 that specifies a dashed line type. The output attributes associated with a 
bundle table index constitute that index’s representation. 


When you call an output function, DEC GKS uses the current, individual 
output values stored in the DEC GKS state list, by default. If you wish 

to use the device-dependent bundle table indexes, you must change the 
attribute’s aspect source flag (ASF). The ASF's are described in Section 5.2.1. 


If you use bundled attributes for primitives, you may be able to change 
the appearance of the generated primitive by redefining its bundle index 
representation. For many workstations, changing index representations 
requires an implicit regeneration, which erases all primitives not contained 
in segments. For complete information concerning the representation 
functions, refer to Section 5.2.2. 


To review the initial individual output attributes, refer to Appendix C, DEC 
GKS Attribute Values. To review the bundle tables available on a given 
workstation, refer to the DEC GKS Device Specifics Reference Manual. 


5.2.1 Aspect Source Flags (ASFs) 


When you call an output function, DEC GKS uses the individual output 
attributes by default. To use bundle tables of attributes, you must establish 
a set of aspect source flags (ASFs). 


The set of ASFs is a thirteen-element integer array, one element for every 
nongeometric output attribute (element 1 corresponds to the line type 
attribute, element 2 corresponds to the line width scale factor attribute, and 
so forth). Each element contains either the value GKS$K_ASF_BUNDLED 
(0) or the value GKS$K_ASF_INDIVIDUAL (1). By passing this array 

to the function SET ASPECT SOURCE FLAGS, DEC GKS uses either the 
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individual attribute value or the bundled value in the bundle table specified 
by the current bundle index. 


For example, the following code illustrates the use of ASFs: 


' CALL GKSS$SET_PLINE LINETYPE( GKS$K_LINETYPE_SOLID ) 


Cc This function call produces a solid line. 
CALL GKSSPOLYLINE( 2, PX, PY ) 


c ASF_FLAGS is a thirteen-element integer array. The first 
element corresponds to the line type attribute. 
ASF_FLAGS( 1 ) = GKS$K_ASF_BUNDLED 
CALL GKSSSET_ASF( ASF_FLAGS ) 


Polyline bundle index number 3 specifies a dashed line 


Cc 
Cc on this workstation. 
CALL GKSS$SET_PLINE_INDEX ( 3 ) 
Cc This call produces a dashed line. 


CALL GKSSPOLYLINE( 2, PX, PY ) 


For a complete discussion of ASFs, refer to the SET ASPECT SOURCE 
FLAGS function description in this chapter. 


NOTE 


If you store primitives in a segment and if you want to be able 

to change the primitive’s appearance elsewhere in the program, 
you must set the primitive’s ASF to be GKS$K_ASF_BUNDLED 
before you generate the primitive. In this way, the primitive’s 
ASF is stored in the segment with the primitive. If you want to 
change the primitive’s appearance, you call the appropriate SET 
REPRESENTATION function (see Section 5.2.2) for the primitive’s 
bundle index. If you store the primitive in a segment using 
individual attributes, the appearance of the primitive cannot be 
changed. 
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5.2.2 Dynamic Changes and Implicit Regeneration 


When working with bundled attributes, you can use any bundle index value 
predefined by your workstation. You can even alter the existing bundles 
table entries, or create new entries, using the representation functions (SET 
POLYLINE REPRESENTATION, SET POLYMARKER REPRESENTATION, 
and so forth). 


If you use the representation functions, use caution. Depending on the 
capabilities of your workstation, DEC GKS may implement the change 
immediately, or the change may require an implicit regeneration of the 
surface. An implicit regeneration clears the screen and only redraws the 
visible segments. You lose all primitives not contained in segments. Many of 
the DEC GKS supported workstations suppress implicit regenerations since 
they cause you to lose all primitives not contained in segments. 


For a detailed discussion of implicit regeneration, refer to Chapter 3, Control 
Functions. 


5.3 Foreground and Background Colors 


The default color index value is 1, which corresponds to the workstation’s 
foreground color. All the default individual color indexes in the DEC GKS 
state list are set to the value 1. 


On a GKS$K_WSCAT_OUTIN or GKS$K_WSCAT_OUTPUT workstation, 
the color of a “blank” surface is called the background color. The color of 
characters written to the workstation surface is called the foreground color. 


Unless you change these color index values using the function SET 
COLOR REPRESENTATION, the color index value 0 corresponds to 

the workstation’s default background color, and the color index value 1 
corresponds to the workstation’s default foreground color. If the workstation 
supports more than two color indexes, values greater than 1 correspond to 
alternative foreground colors. 


5.4 Output Attribute Inquiries 


The following list presents the inquiry functions that you can use to obtain 
output attribute information when writing device-independent code: 


INQUIRE COLOR FACILITIES 
INQUIRE COLOR REPRESENTATION 
INQUIRE CURRENT INDIVIDUAL ATTRIBUTE VALUES 


Output Attribute Functions 5-7 


INQUIRE CURRENT PRIMITIVE ATTRIBUTE VALUES 
INQUIRE FILL AREA FACILITIES 

INQUIRE FILL AREA REPRESENTATION 

INQUIRE LIST OF COLOR INDICES 

INQUIRE LIST OF FILL AREA INDICES 

INQUIRE LIST OF PATTERN INDICES 

INQUIRE LIST OF POLYLINE INDICES 

INQUIRE LIST OF POLYMARKER INDICES 

INQUIRE LIST OF TEXT INDICES 

INQUIRE MAXIMUM LENGTH OF WORKSTATION STATE TABLE 
INQUIRE SET OF OPEN WORKSTATIONS 

INQUIRE PATTERN FACILITIES 

INQUIRE PATTERN REPRESENTATION 

INQUIRE POLYLINE FACILITIES 

INQUIRE POLYLINE REPRESENTATION 

INQUIRE POLYMARKER FACILITIES 

INQUIRE POLYMARKER REPRESENTATION 

INQUIRE PREDEFINED COLOR REPRESENTATION 
INQUIRE PREDEFINED FILL AREA REPRESENTATION 
INQUIRE PREDEFINED PATTERN REPRESENTATION 
INQUIRE PREDEFINED POLYLINE REPRESENTATION 
INQUIRE PREDEFINED POLYMARKER REPRESENTATION 
INQUIRE PREDEFINED TEXT REPRESENTATION 
INQUIRE TEXT FACILITIES 

INQUIRE TEXT REPRESENTATION 


For more information concerning device-independent programming, refer to 
the DEC GKS User Manual. 


5.5 Function Descriptions 
These sections describe each of the DEC GKS attribute functions by 


category: polyline attributes, polymarker attributes, text attributes, fill area 
attributes, attribute source flags, and representation functions. 
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Fill Area Attributes 


Fill Area Attributes 


The DEC GKS functions described in this section affect the following 
geometric and nongeometric fill attributes: 


¢ Color index (nongeometric) 

e Bundle index (nongeometric) 

e Interior style (nongeometric) 

e Style index (nongeometric) 

e Pattern reference point (geometric) 

e Pattern size (geometric) 

Each of these functions can alter the default values used in subsequent calls 


to the FILL AREA function. For more information concerning FILL AREA, 
refer to Chapter 4, Output Functions. 
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Fill Area Attributes 
SET FILL AREA COLOR INDEX 


SET FILL AREA COLOR INDEX 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET FILL AREA COLOR INDEX sets the current fill color 
index entry in the DEC GKS state list to the specified index value. 


Syntax 
GKS$SET_FILL_COLOR_INDEX (color_index) 
GSFACI (cindex) 
gsetfillcolourind (colour) 
Arguments 
color_index 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the fill area color index. The default value for the fill area 
color index entry is the value 1, which designates the default foreground 
color. If a device cannot fill an area with the specified color, DEC GKS uses 
workstation-dependent color. For more information concerning predefined 
color indexes, refer to the DEC GKS Device Specifics Reference Manual. 
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Fill Area Attributes 
SET FILL AREA COLOR INDEX 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG 20 GKS not in proper state: GKS in 
the error state in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 


must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


92 GKS$_ERROR 92 Color index is less than zero in 
routine **** 
Program Example 


Example 5-1 illustrates the use of the function SET FILL AREA COLOR 
INDEX. Following the program example, Figure 5-1 illustrates the 
program’s effect on a VT241 workstation. 
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Fill Area Attributes 
SET FILL AREA COLOR INDEX 


Example 5-1: Changing the Fill Color Index 


aQqQa 


This 


program changes the fill color of a triangle from 


the default color green to the color blue. 
IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS ID, BLUE, NUM_POINTS 


DATA 


DATA 


DATA 
REAL 


WS_ID / 1 /, BLUE / 3 /, NUM_POINTS / 3 / 
PX fsly 49. 4a/ 
PY /.1, .9, .9/ 
PX( 3), PY( 3 ) 


GKS$OPEN_GKS( 'SYSSERROR:’ ) 
GKS$OPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
GKSS$ACTIVATE_WS( WS_ID ) 


GKS$SET_FILL_COLOR_INDEX( BLUE ) 
GKS$FILL_AREA( NUM_POINTS, PX, PY ) 


GKS$DEACTIVATE_WS( WS_ID ) 
GKSS$CLOSE_WS( WS_ID ) 
GKS$CLOSE_GKS () 


The following numbers correspond to the numbers in the previous example: 


@ PX contains the polygon’s X world coordinate values and PY contains the 


Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .1). 


The function SET FILL AREA COLOR INDEX changes the color from 
the default color to blue, but only if the fill area color ASF is set to 
GKS$K_ASF_INDIVIDUAL (the default setting). 


Workstations other than the VT241 may predefine a different represen- 
tation of color index 3 (a color other than blue). 


Figure 5-1 shows the screen of a VT241 terminal after the program has run 
to completion. 
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| Fill Area Attributes 
SET FILL AREA COLOR INDEX 


Figure 5-1: Changing the Fill Color Index—VT241 
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Fill Area Attributes 
SET FILL AREA INDEX 


SET FILL AREA INDEX 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET FILL AREA INDEX establishes the index value pointing 
into the fill area bundle table. The fill area bundle table contains entries 
for the fill area interior style, fill area style index, and fill area color index 
attribute values. When calling FILL AREA, DEC GKS uses the bundle table 
only if the corresponding attribute source flag has been set to GKS$K_ASF_ 
BUNDLED. 


For a list of the predefined fill area bundles for each workstation, refer to 
the DEC GKS Device Specifics Reference Manual. 


Syntax 
GKS$SET_FILL_INDEX (index) 
GSFAI (index) 
gsetfillind (index) 
Arguments 
index 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the fill area bundle index. The default bundle index is 
the value 1. For more information concerning predefined fill area bundle 
indexes, refer to the DEC GKS Device Specifics Reference Manual. 
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Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_ 20 
8 GKS$_ERROR_8 

80 GKS$_ERROR_80 


Program Example 


Fill Area Attributes 
SET FILL AREA INDEX 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 
GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 


routine **** 


Fill area index is invalid in routine 
MK 


Example 5-2 illustrates the use of the function SET FILL AREA INDEX. 
Following the program example, Figure 5—2 illustrates the program’s effect 


on a VT241 workstation. 
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Fill Area Attributes 
SET FILL AREA INDEX 


Example 5-2: Changing the Fill Index 


This program sets the Attribute Source Flags (ASFs) to bundled, 
and then displays the effects of using the first 10 index values 
in calls to GKS$SET_ FILL INDEX. 

IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, NUM_POINTS, INCR 

DATA WS_ID / 1 /, NUM_POINTS / 3 / 


1) DATA PX /.1, .9, .1/ 
DATA PY /.1, .9, .9/ 
REAL PX( 3), PY¥( 3) 
INTEGER FLAGS( 13 ) 
CHARACTER*2 STR 


Qqaaa 


CALL GKSS$OPEN_GKS( 'SYS$ERROR:’ ) 
CALL GKS$OPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


e FLAGS( 11 ) = GKS$K_ASF_ BUNDLED 
FLAGS( 12 ) = GKS$K_ASF BUNDLED 
FLAGS( 13 ) = GKS$K_ASF_BUNDLED 


CALL GKS$SET_ASF( FLAGS ) 


3) DO 200 INCR = 1, 10, 1 
CALL GKS$CLEAR_WS( WS ID, GKS$K_CLEAR_ALWAYS ) 
CALL GKS$SET FILL INDEX( INCR ) 
CALL GKSSFILL AREA( NUM POINTS, PX, PY ) 


4) CALL LIBSCVT_DX_DX( %DESCR( INCR ), %DESCR( STR ) ) 
CALL GKS$SET_TEXT_HEIGHT( 0.03 ) 
CALL GKSSTEXT( .5, .4, ‘Index: /’) 
CALL GKSSTEXT( .8, .4, %DESCR( STR ) ) 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKSSUPDATE _WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


200 CONTINUE 


CALL GKS$DEACTIVATE WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example. 


@ PX contains the polygon’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .1). 
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Fill Area Attributes 
SET FILL AREA INDEX 


@ This code initializes the elements of the array that affect all the non- 


geometric polymarker attributes. This code sets the fill area ASFs to 

GKS$K_ASF_BUNDLED. The parameter flags( 11 ) corresponds to the 
current fill area interior style, flags( 12 ) corresponds to the current fill 
area style index, and flags(:13 ) corresponds to the fill area color index. 


See the SET ASPECT SOURCE FLAGS function description in this 
chapter for more information. 


This code displays the triangle using ten of the fill area index values 
available on the VT241. This code writes the index value that produced 
the fill area, to the right of the triangle. 


This VMS Run-Time Library Routine translates the variable INCR to a 
text string so that TEXT can write the fill area index value to the screen. 


Figure 5-2 shows the screen of a VT241 terminal after the program has run 
to completion. The color of the filled area is green. 
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Fill Area Attributes 
SET FILL AREA INDEX 


Figure 5-2: Changing the Fill Index—VT241 
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Fill Area Attributes 
SET FILL AREA INTERIOR STYLE 


SET FILL AREA INTERIOR STYLE 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET FILL AREA INTERIOR STYLE sets the current fill area 
interior style entry in the DEC GKS state list to be hollow, solid, pattern, or 
hatched. 


If you select solid, FILL AREA fills the color designated by the current fill 
area color index. 


If you select pattern, FILL AREA replicates a pattern (alternating colors) 
to fill the interior of the polygon. The fill area attributes pattern size and 
pattern reference point define the size and position of the start of the pattern 
(see SET PATTERN SIZE and SET PATTERN REFERENCE POINT in this 
section). The fill area style index specifies the pattern to replicate (see SET 
FILL AREA STYLE INDEX in this section). Patterns cover underlying 
primitives. 

If you select hatched, FILL AREA fills the interior of the polygon with 

a series of designs in the color specified by the fill area color index. The 
fill area style index specifies the chosen hatch style. White spaces within 
hatches do not cover underlying primitives. 


GKS$SET_FILL_INT_STYLE (int_style) 
GSFAIS (style) 
gsetfillintstyle (style) 
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Fill Area Attributes 
SET FILL AREA INTERIOR STYLE 


Arguments 
int_style 
data type: integer 
access: read-only 
' mechanism: by reference 


This argument designates the fill area interior style. The argument can be 
any of the following values or constants: 


Value Constant Description 

0 GKS$K_INTSTYLE_HOLLOW Use an outline. 

1 GKS$K_INTSTYLE_SOLID Use a color. 

2 GKS$K_INTSTYLE_PATTERN Use a pattern. 

3 GKS$K_INTSTYLE_HATCH Use crossed or parallel lines. 


Error Messages 


Error Completion 

Number Status Code Message 

-11 DECGKS$_ERROR_NEG_11 Invalid value specified for fill area 
interior style in routine **** 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 


must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 
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Program 


Fill Area Attributes 
SET FILL AREA INTERIOR STYLE 


Example 


Example 5-3 illustrates the use of the function SET FILL AREA INTERIOR 
STYLE. Following the program example, Figure 5-3 illustrates the 
program’s effect on a VT241 workstation. 


Example 5-3: Changing the Fill Area Interior Style 


Cc This program splits a rectangle in half and then 
Cc fills both halves with different styles. 
IMPLICIT NONE 
INCLUDE ’SYSS$LIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, NUM_POINTS, DARK_BLUE PAT 
DATA WS_ID / 1 /, NUM POINTS / 3 /, 
* DARK BLUE PAT / 6 / 


DATA PX /.1, .9, .1/ 
DATA PY /.1, .9, .9/ 
DATA PX2 /.1, .9, .9/ 
DATA, PY2 4/0150 ody. Of 
REAL PX( 3 ), PY( 3 ), PX2( 3 ), PY2( 3 ) 


CALL GKSSOPEN_GKS( ‘’SYSSERROR:’ ) 


CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240) 
CALL GKSSACTIVATE_WS( WS_ID ) 


CALL GKS$FILL_AREA( NUM_POINTS, PX, PY ) 

CALL GKS$SET_FILL_INT STYLE( GKS$K_INTSTYLE_PATTERN ) 
CALL GKS$SET_FILL STYLE _INDEX( DARK BLUE _PAT ) 

CALL GKSS$FILL_AREA( NUM POINTS, PX2, PY2 ) 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKSS$CLOSE_GKS() 

END 


The following numbers correspond to the numbers in the previous example: 


@ The arrays PX and PY contain the polygon’s world coordinate values. 
For example, the first element in both arrays specifies the first point 
(21,1): 


@ In the call to FILL AREA, you specify that there are three points in the 
polygon, as well as the arrays containing the world coordinate points. 
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Fill Area Attributes 
SET FILL AREA INTERIOR STYLE 


© This code changes the interior fill attribute from hollow to pattern 
as long as the current interior fill style ASF is set to GKS$K_ASF_ 
INDIVIDUAL (the default setting). 


@ This code changes the style to a style index that produces a dark blue 
pattern by alternating blue and black colors, as long as the current fill 
area style ASF is set to GKS$K_ASF_INDIVIDUAL (the default setting). 


Workstations other than the VT241 may use other style values to specify 
a similar pattern. See SET FILL AREA INTERIOR STYLE in this 
section for more information. 


Figure 5-3 shows the effects of the calls to FILL AREA. The color of the top 
triangle is hollow green and the bottom triangle is a dark blue pattern. 


Figure 5-3: Changing the Fill Area Interior Style—VT241 
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Fill Area Attributes 
SET FILL AREA STYLE INDEX 


SET FILL AREA STYLE INDEX 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET FILL AREA STYLE INDEX sets the current fill area style 
index entry in the DEC GKS state list to the specified index value. 


This function sets a specific pattern or hatch style to fill the interior of 

a polygonal fill area. If the interior style is hollow or solid, the current 
style index is ignored for the call to FILL AREA. If the interior style is 
pattern, you must pass a pattern index value to this function. If the interior 
style is hatch, you must pass a hatch style value to this function. For 
device-dependent hatch styles, the hatch style index is always a negative 
number. 


Syntax 
GKS$SET_FILL_STYLE INDEX (style_index) 
GSFASI (sindex) 
gsetfillstyleind (index) 
Arguments 
style_index 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the fill area style index. For information on the predefined 
hatch and pattern styles, refer to the DEC GKS Device Specifics Reference 
Manual. The initial fill area style index entry is the value 1. If you 
request a style index that is not available on a particular workstation, that 
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Fill Area Attributes 
SET FILL AREA STYLE INDEX 


workstation uses the style index 1. If the style index 1 is not present on the 
workstation, the result is workstation dependent. 


Error Messages 


Error Completion 

Number Status Code 

-20 DECGKS$_ERROR_NEG_20 
8 GKS$_ERROR_8 

84 GKS$_ERROR_84 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 

Style (pattern or hatch) index is 
equal to zero in routine **** 


Program Example 


Refer to Example 5-3 in this section for a program example using a call to 


SET FILL AREA STYLE INDEX. 
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Fill Area Attributes 
SET PATTERN REFERENCE POINT 


SET PATTERN REFERENCE POINT 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET PATTERN REFERENCE POINT sets the geometric 
attribute current pattern reference point entry in the DEC GKS state list. 
This attribute represents the starting point for a pattern used to fill the 
designated area. DEC GKS uses this value for all subsequent calls to FILL 
AREA until you specify another value. 


NOTE 


Most of the DEC GKS supported workstations do not fully support 
this function. Those workstations that do not, do accept the 
function call but do not make any changes to the pattern. For 
more information, refer to the DEC GKS Device Specifics Reference 
Manual. 


GKS$SET_PAT_REF_PT (x_coordinate, y_coordinate) 
GSPARF (px, py) 
gsetpatrefpt (patref) 
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Fill Area Attributes 
SET PATTERN REFERENCE POINT 


Arguments 


x_coordinate 
y_coordinate 


data type: real 
access: read-only 
mechanism: by reference 


These arguments designate the X and Y world coordinate unit values of the 


pattern starting point. 


Error Messages 
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Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
8 GKS$_ERROR_8 


Output Attribute Functions 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


Fill Area Attributes 
SET PATTERN SIZE 


SET PATTERN SIZE 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET PATTERN SIZE specifies the geometric attribute current 
pattern size entry in the DEC GKS state list, which is the height and width 
vectors in world coordinate units. The pattern size is replicated for use 
within a fill area. DEC GKS uses this value for all subsequent calls to FILL 
AREA until you specify another value. 


NOTE 


Most of the DEC GKS supported workstations do not fully support 
this function. Those workstations that do not, do accept the 
function call but do not make any changes to the pattern. For 
more information, refer to the DEC GKS Device Specifics Reference 
Manual. 


GKS$SET_PAT_SIZE (pattern_width, pattern_height) 
GSPA (px, py) 
gsetpatsize (patsize) 
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Fill Area Attributes 
SET PATTERN SIZE 


Arguments 


pattern_width 
pattern_height 


data type: real 
access: read-only 
mechanism: by reference 


These arguments specify the width and height in world coordinates units. 
DEC GKS begins replicating the pattern representation at the pattern 
reference point, and continues until the polygonal fill area in world 
coordinate space is filled with the pattern. 


Error Messages 


Error Completion 

Number Status Code Message 

-20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 


must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 


routine **** 


87 GKS$_ERROR_87 Pattern size value is not positive 
in routine **** 
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Polyline Attributes 


Polyline Attributes 


The DEC GKS functions described in this section affect the following 
polyline attributes: 


e Color index (nongeometric) 

¢ Bundle index (nongeometric) 

e Line type (nongeometric) 

e Line width scale factor (nongeometric) 

Depending on the ASF for the output attribute, each of these functions can 


alter the default values used in subsequent calls to POLYLINE. For more 
information concerning POLYLINE, refer to Chapter 4, Output Functions. 
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Polyline Attributes 
SET LINETYPE 


SET LINETYPE 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET LINETYPE sets the current polyline line type entry in the 
DEC GKS state list to be solid, dashed, dotted, dashed-dotted, or any one of 
the device-dependent types. . 


Every workstation capable of output (DEC GKS category GKS$K_WSCAT_ 
OUTPUT or GKS$K_WSCAT_OUTIN) defines at least four line types. For 
more information concerning possible polyline line type values, réfer to the 
DEC GKS Device Specifics Reference Manual. 


Syntax 
GKS$SET_PLINE_LINETYPE (line_type) 
GSLN (ltype) 
gsetlinetype (type) 
Arguments 
line_type 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the polyline line type. The argument can be any of the 
following values or constants. 
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Polyline Attributes 


SET LINETYPE 
Value Constant Description 
<0 Device-dependent types. 
1 GKS$K_LINETYPE_SOLID Use solid line. 
2 GKS$K_LINETYPE_DASHED Use dashed line. 
3 GKS$K_LINETYPE_DOTTED Use dotted line. 
4 GKS$K_LINETYPE_DASHED_DOTTED Use dashed-dotted line. 
>= 5 Reserved: future standard- 


ization. 


The default for the current line type value is 1, which displays a solid 
line. If you specify an unsupported line type, DEC GKS uses GKS$K_ 
LINETYPE_SOLID. For more information concerning predefined line type 
indexes, refer to the DEC GKS Device Specifics Reference Manual. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 


must be in one of the states . 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


63 GKS$_ERROR_63 Specified linetype is equal to zero 
in routine **** 
Program Example 


Example 5—4 illustrates the use of the function SET LINETYPE. Following 
the program example, Figure 5—4 illustrates the program’s effect on a VT241 
workstation. 
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Polyline Attributes 


SET LINETYPE 


Example 5-4: Changing the Polyline Line Type 


This 


QQq 


program changes the solid lines of an arrow to 


dashed and dotted lines. 


IMPLICIT NONE 
INCLUDE '’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, NUM_POINTS 


DATA 
REAL 
@ DATA 
DATA 


CALL 
CALL 
CALL 


2] CALL 
CALL 


CALL 
CALL 
CALL 
END 


WS_ID / 1 /, NUM_POINTS / 5 / 


Pxt 5) )y BYU S.) 
PYf ely 29 2ty. as hos 
PY/35 50 050 6p 645 5S 


GKSSOPEN_GKS( 'SYS$ERROR:’ ) 
GKSSOPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240) 
GKSSACTIVATE_WS( WS_ID ) 


GKS$SET_PLINE_LINETYPE( GKS$K_LINETYPE_DASHED DOTTED ) 
GKSSPOLYLINE( NUM_POINTS, PX, PY ) 


GKS$DEACTIVATE_WS( WS_ID ) 
GKS$CLOSE_WS( WS_ID ) 
GKSS$CLOSE_GKS () 


The following numbers correspond to the numbers in the previous example: 


@ PX contains the polygon’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .5). 


@ The function SET LINETYPE changes the line type from the default 


type to dashed and dotted, only if the line type ASF is set to GKS$K_ 
ASF_INDIVIDUAL (the default setting). 


Figure 5—4 shows the screen of a VT241 terminal after the program has run 
to completion. The arrow changed from the default line type solid to the 
type dashed-dotted. 
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Polyline Attributes 
SET LINETYPE 


Figure 5-4: Changing the Polyline Line Type—VT241 
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Polyline Attributes 
SET LINEWIDTH SCALE FACTOR 


SET LINEWIDTH SCALE FACTOR 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET LINEWIDTH SCALE FACTOR sets the current polyline 
line width scale factor entry in the DEC GKS state list. 


DEC GKS calculates line width as the nominal line width, multiplied by the 
line width scale factor. The line width scale factor is a real number that you 
pass to SET LINEWIDTH SCALE FACTOR. The graphics handler maps the 
value to the nearest available line width defined by the graphics handler. 


Syntax 
GKS$SET_PLINE_LINEWIDTH  (line_width_ scale_factor) 
GSLWSC_ (Iwiath) 
gsetlinewidth (width) 
Arguments 
line_width_scale_factor 
data type: real 
access: read-only 
mechanism: by reference 


This argument is the line width scale factor. The default for the current 
entry is the value 1.0, which outputs a line of the nominal width. 
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Polyline Attributes 


SET LINEWIDTH SCALE FACTOR 


Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
8 GKS$_ERROR_8 

65 GKS$_ERROR_65 


Program Example 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 

Linewidth scale factor is less than 
zero in routine **** 


Example 5-5 illustrates the use of the function SET LINEWIDTH SCALE 
FACTOR. Following the program example, Figure 5-5 illustrates the 


program’s effect on a VT241 workstation. 
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Polyline Attributes 
SET LINEWIDTH SCALE FACTOR 


Example 5-5: Changing the Polyline Line Width 


C This 


program increases the line width of an arrow 5 times. 


IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, NUM_POINTS 


REAL 
DATA 


MIN_TIMES FIVE 
WS_ID / 1 /, NUM POINTS / 5 /, 


* MIN TIMES FIVE / 5.0 / 


REAL 


0 DATA 
DATA 


CALL 
CALL 
CALL 


2) CALL 


CALL 


The following numbers correspond to the numbers in the previous example: 


@ PX contains the polygon’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 


PX( 5), PY( 5 ) 
PX /.1, .9, .7, .7, .9/ 
PY /.5, .5, .6, .4, .5/ 


GKSSOPEN_GKS( ‘SYSSERROR:’ ) 
GKSS$OPEN _WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240) 
GKSS$ACTIVATE_WS( WS_ID ) 


GKS$SET_PLINE_LINEWIDTH( MIN_TIMES FIVE ) 
GKSSPOLYLINE( NUM_POINTS, PX, PY ) 


GKS$DEACTIVATE _WS( WS_ID ) 
GKSS$CLOSE_WS( WS_ID ) 
GKS$CLOSE_GKS () 


specifies the first point (.1, .5). 


@ The function SET LINEWIDTH SCALE FACTOR changes the line width 
from the nominal width to five times the nominal width, only if the line 
width scale factor ASF is set to GKS$K_ASF_INDIVIDUAL (the default 


setting). 


Figure 5-5 shows the screen of a VT241 terminal after the program has run 


to completion. 
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Polyline Attributes 
SET LINEWIDTH SCALE FACTOR 


Figure 5-5: Changing the Polyline Line Width—VT241 
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Polyline Attributes 
SET POLYLINE COLOR INDEX 


SET POLYLINE COLOR INDEX 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET POLYLINE COLOR INDEX sets the current polyline color 
index DEC GKS state list entry to the specified index value. 


Syntax 
GKS$SET_PLINE_COLOR_INDEX (color_index) 
GSPLCI (cindex) | 
gsetlinecolourind (co/our) 
Arguments 
color_index 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the polyline color index. DEC GKS uses the default 
foreground color for default polyline color index (1). For more information 
concerning predefined color indexes, refer to the DEC GKS Device Specifics 
Reference Manual. 
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Polyline Attributes 
SET POLYLINE COLOR INDEX 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 


must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


92 GKS$_ERROR_92 Color index is less than zero in 
routine **** 
Program Example 


Example 5-6 illustrates the use of the function SET POLYLINE COLOR 
INDEX. Following the program example, Figure 5-6 illustrates the 
program’s effect on a VT241 workstation. 
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Polyline Attributes 
SET POLYLINE COLOR INDEX 


Example 5-6: Changing the Polyline Color Index 


Cc This 


program changes the color of an arrow from green to blue. 


IMPLICIT NONE 
INCLUDE '’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, BLUE, NUM_POINTS 


DATA 
REAL 
1] DATA 


DATA 


CALL 
CALL 
CALL 


@ CALL 
CALL 


CALL 
CALL 
CALL 
END 


WS ID / 1/, BLUE / 3 /, NUM_POINTS / 5 / 
PX( 5), PY¥( 5) 

PREPS oO oT. ky OL 

BY /,5 5.5). 66,4457 07 


GKS$OPEN_GKS( 'SYSS$ERROR:’ ) 
GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240) 
GKSSACTIVATE WS( WS_ID ) 


GKS$SET_PLINE_COLOR_INDEX( BLUE ) 
GKS$POLYLINE( NUM POINTS, PX, PY ) 


GKSSDEACTIVATE_WS( WS_ID ) 
GKSSCLOSE_WS( WS_ID ) 
GKSS$CLOSE_GKS () 


The following numbers correspond to the numbers in the previous example: 


@ PX contains the polygon’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .5). 

@ The function SET POLYLINE COLOR INDEX changes the color from 


the default color to blue, but only if the polyline color ASF is set to 
GKS$K_ASF_INDIVIDUAL (the default setting). 


The VT241 predefines the index value 3 to represent the color blue. 
Workstations other than the VT241 may predefine a different represen- 
tation of color index 3 (a color other than blue). 


Figure 5-6 shows the screen of a VI241 terminal after the program has run 
to completion. The arrow changed from the default color green to the color 


blue. 
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Polyline Attributes 
SET POLYLINE COLOR INDEX 


Figure 5-6: Changing the Polyline Color Index—VT241 
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Polyline Attributes 
SET POLYLINE INDEX 


SET POLYLINE INDEX 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET POLYLINE INDEX establishes the index value pointing 
into the polyline bundle table. The polyline bundle table contains entries 
for the polyline color index, polyline line type, and polyline linewidth scale 
factor attribute values. When calling POLYLINE, DEC GKS uses the 
bundle table only if the corresponding attribute source flag has been set to 
GKS$K_ASF_BUNDLED. 


For a list of the predefined polyline bundle entries for each workstation, 
refer to the DEC GKS Device Specifics Reference Manual. 


Syntax 
GKS$SET_PLINE_INDEX (index) 
GSPLI (pindex) 
gsetlineind (index) 
Arguments 
index 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the polyline bundle index. The default bundle index is the 
value 1. For more information concerning possible polyline bundle indexes, 
refer to the DEC GKS Device Specifics Reference Manual. 
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Error Messages 


Error Completion 

Number Status Code 

-20 DECGKS$_ERROR_NEG_20 
8 GKS$_ERROR_8 

60 GKS$_ERROR_60 


Program Example 


Polyline Attributes 
SET POLYLINE INDEX 


Message 


GKS not in proper state: GKS in 
the error. state in routine **** 
GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


Polyline index is invalid in routine 
RK 


Example 5-7 illustrates the use of the function SET POLYLINE INDEX. 
Following the program example, Figure 5—7 illustrates the program’s effect 


on a VT241 workstation. 
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Polyline Attributes 
SET POLYLINE INDEX 


Example 5-7: Changing the Polyline Index 


This program sets the Attribute Source Flags (ASFs) to bundled, 
and then displays the effects of using the first 10 index values 
in calls to GKS$SET_PLINE_INDEX. 

IMPLICIT NONE 

INCLUDE 'SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, NUM_POINTS, INCR 

DATA WS_ID / 1 /, NUM_POINTS / 5 / 

REAL PX( 5 ), PY( 5 ) 

1] DATA PX /.1, .9, .7, «7, -9/ 

DATA PY: -/.5y. <5). 26; 34, <5/ 

INTEGER FLAGS( 13 ) 

CHARACTER*2 STR 


Qqaa 


CALL GKSSOPEN_GKS( ‘SYSS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKSS$ACTIVATE WS( WS_ID ) 


2] FLAGS( 1 ) = GKS$K_ASF_BUNDLED 
FLAGS( 2 ) = GKS$K_ASF_ BUNDLED 
FLAGS( 3 ) = GKS$K_ASF_BUNDLED 


CALL GKS$SET_ASF( FLAGS ) 


© DO 200 INCR = 1, 10, 1 
CALL GKSS$CLEAR_WS ( WS_ID, GKS$K_CLEAR_ALWAYS ) 
CALL GKS$SET_PLINE_INDEX ( INCR ) 
CALL GKSSPOLYLINE ( NUM_POINTS, PX, PY ) 


4) CALL LIBSCVT_DX_DX( %DESCR( INCR ), %DESCR( STR ) ) 
CALL GKS$SET_TEXT_HEIGHT( 0.03 ) 
CALL GKS$TEXT( .1, .3, ‘Index: ’) 
CALL GKSSTEXT( .4, .3, %SDESCR( STR ) ) 


C Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


200 CONTINUE 


CALL GKSSDEACTIVATE WS( WS_ID ) 
CALL GKSSCLOSE_WS( WS_ID ) 

CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example. 


@ PX contains the polygon’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .5). 
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Polyline Attributes 
SET POLYLINE INDEX 


@ This code initializes the elements of the array that affect all the non- 


geometric polyline attributes. This code sets the three polyline ASFs to 
GKS$K_ASF_BUNDLED. The parameter flags( 1 ) corresponds to the 
line type, flags( 2 ) corresponds to the line width scale factor, and 

flags( 3 ) corresponds to the polyline color index. 

See the SET ASPECT SOURCE FLAGS function description in this 
chapter for more information. 

This code displays the arrow using ten of the polyline index values 
available on the VT241. This code writes the index value that produced 
the polyline, in the lower left portion of the screen. 


This VMS Run-Time Library Routine translates the variable INCR to a 
text string so that TEXT can write the polyline index value to the screen. 


Figure 5—7 shows the screen of a VI241 terminal after the program has run 
to completion. The color of the arrow is green. 
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Polyline Attributes 
SET POLYLINE INDEX 


Figure 5-7: Changing the Polyline Index—VT241 
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Polymarker Attributes 


Polymarker Attributes 


The DEC GKS functions described in this section affect the following poly- 
marker attributes: 


¢ Color index (nongeometric) 

¢ Bundle index (nongeometric) 

e Line type (nongeometric) 

¢ Size (nongeometric) 

Each of these functions can alter the default values used in subsequent 


calls to the POLYMARKER function. For more information concerning 
POLYMARKER, refer to Chapter 4, Output Functions. 
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Polymarker Attributes 
SET MARKER SIZE SCALE FACTOR 


SET MARKER SIZE SCALE FACTOR 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET MARKER SIZE SCALE FACTOR sets the current marker 
size scale factor entry in the DEC GKS state list to the specified value for all 
polymarker types. 


DEC GKS calculates marker size for all types (except the dot marker type) 
as the nominal marker size multiplied by the marker size scale factor. The 
marker size scale factor is a real number that you pass to SET MARKER 
SIZE SCALE FACTOR. The graphics handler maps the value to the nearest 
available marker size defined by the handler. (The dot marker type is 
always the smallest dot that the workstation can produce.) 


GKS$SET_PMARK_SIZE (marker_size_scale_factor) 
GSMKSC (sfactor) 
gsetmarkersize (size) 


Arguments 


marker_size_scale_factor 


data type: real 

access: read-only 

mechanism: by reference 

This argument is the marker size scale factor. The default for the current 
entry is the value 1.0, which outputs a marker of the nominal size as defined 
by the graphics handler. 
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Polymarker Attributes 
SET MARKER SIZE SCALE FACTOR 


Error Messages 


Error Completion 

Number Status Code _ Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 


must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


71 GKS$_ERROR_71 Marker size scale factor is less 
than zero in routine **** 
Program Example 
Example 5-8 illustrates the use of the function SET MARKER SIZE SCALE 


FACTOR. Following the program example, Figure 5-8 illustrates the 
program’s effect on a VT241 workstation. 
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Polymarker Attributes 
SET MARKER SIZE SCALE FACTOR 


5-50 


Example 5-8: Changing the Polymarker Size 


This 
that 


aQqa 


program draws five at five times 
of the default size. 


IMPLICIT NONE 
INCLUDE '’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, NUM_POINTS 


REAL 
DATA 


MIN TIMES FIVE 
WS ID / 1 /, NUM_POINTS / 5 /, 


* MIN TIMES FIVE / 5.0 / 


REAL 


1] DATA 


DATA 


CALL 
CALL 
CALL 


@ CALL 


CALL 


CALL 
CALL 
CALL 
END 


The following numbers correspond to the numbers in the previous example: 


@ PX contains the markers’ X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 


PX( 5 ), PY( 5 ) 
PX /.1, .9, .7, .7, .9/ 
PY /.5, .5, .6, .4, .5/ 


GKSS$OPEN_GKS( 'SYSSERROR:’ ) 
GKS$OPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240) 
GKSSACTIVATE_WS( WS_ID ) 


GKS$SET_PMARK SIZE( MIN TIMES FIVE ) 
GKSSPOLYMARKER( NUM_POINTS, PX, PY ) 


GKS$DEACTIVATE_WS( WS_ID ) 
GKS$CLOSE_WS( WS_ID ) 
GKS$CLOSE_GKS() 


specifies the first point (.1, .5). 


@ The function SET MARKER SIZE SCALE FACTOR changes the marker 
size from the nominal width to five times the nominal width, only if the 
marker size scale factor ASF is set to GKS$K_ASF_INDIVIDUAL (the 


default setting). 


Figure 5-8 shows the screen of a VT241 terminal after the program has run 


to completion. 


Output Attribute Functions 


: Polymarker Attributes 
SET MARKER SIZE SCALE FACTOR 


Figure 5-8: Changing the Polymarker Size—VT241 
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Polymarker Attributes 
SET MARKER TYPE 


SET MARKER TYPE 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET MARKER TYPE sets the current marker type entry in the 
DEC GKS state list to be dots, plus signs, asterisks, circles, diagonal crosses, 
or any of the device-dependent types. 


Every workstation capable of output (of DEC GKS category GKS$K_ 
WSCAT_OUTPUT or GKS$K_WSCAT_OUTIN) defines at least five 
polymarker types. For more information concerning predefined polymarker 
type, refer to the DEC GKS Device Specifics Reference Manual. 


Syntax 
GKS$SET_PMARK_TYPE (marker_type) 
GSMK_  (mtype) 
gsetmarkertype (type) 
Arguments 
marker_type 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the polymarker type. The argument can be any of the 
following values or constants. 
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Value Constant 


<0 

1 GKS$K_MARKERTYPE_DOT 

2 GKS$K_MARKERTYPE_PLUS 

3 GKS$K_MARKERTYPE_ASTERISK 

4 GKS$K_MARKERTYPE_CIRCLE 

5 GKS$K_MARKERTYPE_DIAGONAL_ 
CROSS 

>= 6 


Polymarker Attributes 
SET MARKER TYPE 


Description 
Device-dependent types. 
Use dots (.). 

Use plus signs (+). 

Use asterisks (*). 

Use circles (0). 


Use diagonal crosses (X). 


Reserved: future 
standardization. 


The default index for the current polymarker type entry is GKS$K_ 
MARKERTYPE_ASTERISK. For more information concerning possible line 
type indexes, refer to the DEC GKS Device Specifics Reference Manual. 


Error Messages 


69 


Program Example 


Completion 
Status Code 


DECGKS$_ERROR_NEG_20 


GKS$_ERROR_8 


GKS$_ERROR_69 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


Specified marker type is equal to 
zero in routine **** 


Example 5-9 illustrates the use of the function SET MARKER TYPE. 
Following the program example, Figure 5-9 illustrates the program’s effect 
on a VT241 workstation. 
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Polymarker Attributes 
SET MARKER TYPE | 


Example 5-9: Changing the Polymarker Type 


Cc This 


program draws five circles. 


IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS ID, NUM POINTS 


DATA 
REAL 
1] DATA 

DATA 


CALL 
CALL 
CALL 


e CALL 


CALL 


CALL 
CALL 
CALL 
END 


WS_ID / 1 /, NUM_POINTS / 5 / 
PX({ 5), PY -S:') 

PK fulgr Op. cle ole OF 

PY /e5y 25; 46) 945.357 


GKSSOPEN_GKS( 'SYSSERROR:’ ) 
GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240) 
GKSSACTIVATE WS( WS_ID ) 


GKS$SET_PMARK TYPE( GKS$K_MARKERTYPE_CIRCLE ) 
GKS$POLYMARKER( NUM POINTS, PX, PY ) 


GKSS$DEACTIVATE WS( WS_ID ) 
GKS$CLOSE_WS( WS_ID ) 
GKS$CLOSE_GKS () 


The following numbers correspond to the numbers in the previous example: 


@ PX contains the markers’ X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .5). 


@ The function SET MARKER TYPE changes the polymarker type from 


the default type to circles, only if the marker type ASF is set to GKS$K_ 
ASF_INDIVIDUAL (the default setting). 


Figure 5-9 shows the screen of a VT241 terminal after the program has run 
to completion. 
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Polymarker Attributes 
SET MARKER TYPE 


Figure 5-9: Changing the Polymarker Marker Type—VT241 
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Polymarker Attributes 
SET POLYMARKER COLOR INDEX 


SET POLYMARKER COLOR INDEX 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET POLYMARKER COLOR INDEX sets the current poly- 
marker color index entry in the DEC GKS state list to the specified 
value. 


GKS$SET_PMARK_COLOR_INDEX (color_index) 
GSPMCI (cindex) 
gsetmarkercolourind (colour) 


Arguments 


color_index 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the polymarker color index. The default value for 

the polymarker color index entry is the value 1, which designates the 
workstation’s default foreground color. For more information concerning 
predefined color index values, refer to the DEC GKS Device Specifics 
Reference Manual. 
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Polymarker Attributes 
SET POLYMARKER COLOR INDEX 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 


must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


92 GKS$_ERROR_92 Color index is less than zero in 
routine **** 
Program Example 


Example 5-10 illustrates the use of the function SET POLYMARKER 
COLOR INDEX. Following the program example, Figure 5—10 illustrates the 
program’s effect on a VT241 workstation. 
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Polymarker Attributes 
SET POLYMARKER COLOR INDEX 


Example 5-10: Changing the Polymarker Color Index 


Cc This 


outputs five blue asterisks 


IMPLICIT NONE 
INCLUDE '’SYSS$LIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, BLUE, NUM POINTS 


DATA 
REAL 
0 DATA 
DATA 


CALL 
CALL 
CALL 


e CALL 


CALL 


CALL 
CALL 
CALL 
END 


WS_ID / 1 /, BLUE / 3 /, NUM_POINTS / 5 / 
PX( 5), PY¥( 5 ) 

PX fale 29, wp ST 287 

PY 552.45; 56) 4, 25/ 


GKSSOPEN_GKS( 'SYSSERROR:’ ) 
GKS$OPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240) 
GKS$ACTIVATE_WS( WS_ID ) 


GKS$SET_PMARK_ COLOR_INDEX( BLUE ) 
GKSSPOLYMARKER( NUM_POINTS, PX, PY ) 


GKS$DEACTIVATE WS( WS_ID ) 
GKS$CLOSE_WS( WS_ID ) 
GKS$CLOSE_GKS () 


The following numbers correspond to the numbers in the previous example: 


@ PX contains the markers’ X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .5). 


@ The function SET POLYMARKER COLOR INDEX changes the color 
from the default color to blue, but only if the polymarker color ASF is set 
to GKS$K_ASF_INDIVIDUAL (the default setting). 


Workstations other than the VT241 may predefine a different represen- 
tation of color index 3 (a color other than blue). 


Figure 5-10 shows the screen of a VT241 terminal after the program has 
run to completion. 


5—58 Output Attribute Functions 


Polymarker Attributes 
SET POLYMARKER COLOR INDEX 


Figure 5-10: Changing the Polymarker Color Index—VT241 
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Polymarker Attributes 
SET POLYMARKER INDEX 


SET POLYMARKER INDEX 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET POLYMARKER INDEX establishes the index value 
pointing into the polymarker bundle table. The polymarker bundle table 
contains entries for the polymarker color index, polymarker type, and 
polymarker size scale factor attribute values. When calling POLYMARKER, 
DEC GKS uses the bundle table only if the corresponding attribute source 
flag has been set to GKS$K_ASF_BUNDLED. 


For a list of the predefined polymarker area bundles for each workstation, 
refer to the DEC GKS Device Specifics Reference Manual. 


Syntax 

GKS$SET_PMARK_INDEX (index) 

GSPMI _ (pindex) 

gsetmarkerind (index) 
Arguments 

index 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the polymarker bundle index. The default bundle index is 
the value 1. For more information concerning predefined polymarker bundle 
table indexes, refer to the DEC GKS Device Specifics Reference Manual. 
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Polymarker Attributes 


SET POLYMARKER INDEX 
Error Messages 
Error Completion 
Number Status Code Message 
—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 
8 GKS$_ERROR_8 GKS not in proper state: GKS 


must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 


routine **** 


66 GKS$_ERROR_66 Polymarker index is invalid in 
routine **** 


Program Example 
Example 5-11 illustrates the use of the function SET POLYMARKER 


INDEX. Following the program example, Figure 5-11 illustrates the 
program’s effect on a VT241 workstation. 
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Polymarker Attributes 
SET POLYMARKER INDEX 


Example 5-11: Changing the Polymarker Index 





This program sets the Attribute Source Flags (ASFs) to bundled, 
and then displays the effects of using the first 10 index values 
in calls to GKS$SET_PMARK_ INDEX. 

IMPLICIT NONE 

INCLUDE ’SYSS$LIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, NUM_POINTS, INCR 

DATA WS_ID / 1 /, NUM_POINTS / 5 / 

RBAL PX( 5 ), PY( 5 ) 

0 DATA PX /.1, .9, -7) 7, -9/ 

DATA PY /.5, 25, «6, 64, 25/ 

INTEGER FLAGS( 13 ) 

CHARACTER*2. STR 


aaa 


CALL GKS$OPEN_GKS( ‘’SYSS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE_WS( WS_ID ) 


II 


e FLAGS( 4 ) = GKS$K_ASF_BUNDLED 
FLAGS( 5 ) = GKS$K_ASF_BUNDLED 
FLAGS( 6 ) = GKSS$K_ASF_BUNDLED 
CALL GKS$SET_ASF( FLAGS ) 


@ DO 200 INCR = 1, 10, 1 
CALL GKS$CLEAR_WS( WS ID, GKS$K_CLEAR_ALWAYS ) 
CALL GKS$SET_PMARK INDEX( INCR )- 
CALL GKS$POLYMARKER( NUM POINTS, PX, PY ) 


4] CALL LIBSCVT_DX_DX( %DESCR( INCR ), *DESCR( STR ) ) 
CALL GKS$SET_TEXT_HEIGHT( 0.03 ) 
CALL GKS$TEXT( .1, .3, ‘Index: ’) 
CALL GKSS$TEXT( .4, .3, %DESCR( STR ) ) 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKSS$UPDATE _WS( WS_ID, GKS$K_POSTPONE_ FLAG ) 

READ (5, *) 


200 CONTINUE 


CALL GKSS$DEACTIVATE _WS( WS_ID ) 
CALL GKSSCLOSE_WS( WS_ID ) 

CALL GKSS$CLOSE_GKS() 

END 


The following numbers correspond to the numbers in the previous example. 


@ PX contains the markers’ X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .5). 
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Polymarker Attributes 
SET POLYMARKER INDEX 


@ This code initializes the elements of the array that affect all the nonge- 


4) 


ometric polymarker attributes. This code sets the polymarker ASFs to 
GKS$K_ASF_BUNDLED. The parameter flags( 4 ) corresponds to the 

marker type, flags( 5 ) corresponds to the marker size scale factor, and 
flags( 6 ) corresponds to the polymarker color index. 


See the SET ASPECT SOURCE FLAGS function description in this 
chapter for more information. 


This code displays the arrow using ten of the polymarker index values 
available on the VT241. This code writes the index value that produced 
the polymarker, in the lower left portion of the screen. 

This VMS Run-Time Library Routine translates the variable INCR to a 
text string so that TEXT can write the fill area index value to the screen. 


Figure 5—11 shows the screen of a VT241 terminal after the program has 
run to completion. The markers are green. 


Output Attribute Functions 5-63 


Polymarker Attributes 
SET POLYMARKER INDEX 


Figure 5-11: Changing the Polymarker Index—VT241 
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5-64 Output Attribute Functions 


Text Attributes 


Text Attributes 


The DEC GKS functions described in this section affect the following geo- 
metric and nongeometric text attributes: 


Alignment (geometric) 

Color (nongeometric) 

Expansion factor (nongeometric) 
Font and precision (nongeometric) 
Height (geometric) 

Bundle Index (nongeometric) 
Path (geometric) 

Spacing (nongeometric) 

Up vector (geometric) 


Character strings are defined within a text extent rectangle. A text 
extent rectangle is an imaginary parallelogram that completely contains 
the character string to be written. The character string itself and the 
text attributes character height, character expansion factor, and character 
spacing define the limits of the text extent rectangle. 


Each of these functions can alter the default values used in subsequent 
calls to the TEXT function. For more information concerning TEXT, refer to 
Chapter 4, Output Functions. 
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Text Attributes 
SET CHARACTER EXPANSION FACTOR 


SET CHARACTER EXPANSION FACTOR 


\ 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET CHARACTER EXPANSION FACTOR sets the current 
character expansion factor entry in the DEC GKS state list to the specified 
value. This function alters the width of the generated characters, but not 
the height. 


When DEC GKS calculates the character width using the default character 
height, the resulting text string is legible. However, certain normalization 
transformations distort the text. You can either use SET CHARACTER 
EXPANSION FACTOR or SET CHARACTER HEIGHT to reestablish a 
legible character width. (For more information concerning transformations, 
refer to Chapter 6, Transformation Functions.) 


GKS$SET_TEXT_EXPFAC (expansion_factor) 
GSCHXP  (efactor) 
gsetcharexpan (exp) 


Arguments 


expansion_factor 


data type: real 
access: read-only 
mechanism: by reference 
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Text Attributes 


SET CHARACTER EXPANSION FACTOR 


This argument is the character expansion factor. This value multiplied 
by the width-to-height ratio specified in the original font specification 
determines the new character width. The character height remains the 


same. 


The default for the current character expansion factor is the value 1.0, which 
displays text using the width-to-height ratio specified in the font design. 


Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
—28 DECGKS$_ERROR_NEG_28 
8 GKS$_ERROR_8 

77 GKS$_ERROR_77 


Program Example 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


Invalid value specified for expan- 
sion factor in routine **** 


GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


Character expansion factor is less 


than or equal to zero in routine 
HK 


Example 5-12 illustrates the use of the function SET CHARACTER 
EXPANSION FACTOR. Following the program example, Figure 5-12 
illustrates the program’s effect on a VT241 workstation. 
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Text Attributes 
SET CHARACTER EXPANSION FACTOR 


Example 5—12: Changing the Character Expansion Factor 


This program increases text width by three times the 
nominal size. 

IMPLICIT NONE 

INCLUDE ’SYS$LIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID 

REAL TIMES THREE, START PT X, START PT Y, LARGER 
DATA WS_ID / 1 /, TIMES THREE / 3.0 /, 


* START_PT_X / 0.5 /, START_PT_Y / 0.5 /, 
* LARGER / 0.03 / 


CALL GKSS$OPEN_GKS( ’SYSS$ERROR:’ ) 
CALL GKS$OPEN WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


Make the text easy to read. 
CALL GKS$SET_TEXT HEIGHT( LARGER ) 
CALL GKSS$TEXT( START_PT_X, START_PT_Y, ‘TEXT’ ) 


Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


Clear the screen and generate wider characters. 
CALL GKSS$CLEAR_WS( WS_ID, GKS$K_CLEAR_CONDITIONALLY ) 


CALL GKS$SET_TEXT EXPFAC( TIMES THREE ) 
CALL GKS$TEXT( START PT X, START PTY, ‘TEXT’ ) 


CALL GKSS$DEACTIVATE _WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 

CALL GKS$CLOSE_GKS() 

END 


The following numbers correspond to the numbers in the previous example: 


@ Clear the screen conditionally. 


@ The function SET CHARACTER EXPANSION FACTOR changes the 
expansion factor so that text is displayed three times the width-to-height 
ratio specified in the original font design, but only if the character 
expansion factor ASF is set to GKS$K_ASF_INDIVIDUAL (the default 
setting). 


568 Output Attribute Functions 


Text Attributes 
SET CHARACTER EXPANSION FACTOR 


Figure 5-12 shows the screen of a VT241 terminal after the program has 
run to completion. 


Figure 5-12: Changing the Character Expansion Factor—VT241 
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Text Attributes 
SET CHARACTER HEIGHT 


SET CHARACTER HEIGHT 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function, SET CHARACTER HEIGHT, sets the geometric attribute, 
current character height entry in the DEC GKS state list to the specified 
world coordinate unit value. DEC GKS uses this value for all subsequent 
calls to TEXT until you specify another value. 


If you specify a new height to SET CHARACTER HEIGHT, DEC GKS 
expands text output to the closest height the workstation is capable 

of producing. Exercise caution if you change the size of the current 
normalization window since you may also have to readjust the character 
height. 


Also remember that changing the text height automatically changes the 
character expansion factor and the character spacing, in proportion to 

the text height adjustment. (For more information concerning the world 
coordinate system and transformations, refer to Chapter 6, Transformation 
Functions.) 


GKS$SET_TEXT_HEIGHT (height) 
GSCHH (height) 
gsetcharheight (height) 
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Text Attributes 
SET CHARACTER HEIGHT 


Arguments 
height 
data type: real 
access: read-only 
mechanism: by reference 


This argument is the character height; it specifies the character height in 
world coordinate units. Text height is an absolute value. 


The default for the current text height is the world coordinate unit value 
0.01. The absolute world coordinate value 0.01 is one percent of the default 
normalization window height (1.0). 


Error Messages 


Error Completion 

Number Status Code Message 

~20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 


must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


77 GKS$_ERROR_77 Character height is less than or 
equal to zero in routine **** 


Program Example 
Example 5-13 illustrates the use of the function SET CHARACTER 


HEIGHT. Following the program example, Figure 5-13 illustrates the 
program’s effect on a VT241 workstation. 
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Text Attributes 
SET CHARACTER HEIGHT 


Example 5-13: Changing the Text Height 


Cc This program increases character height. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID 
REAL THIRD_WC_POINT, START _PT _X, START PT Y 
DATA WS_ID / 1 /, THIRD_WC_POINT / 0.03 /, 
* START _PT X / 0.1 /, START PT Y / 0.5 / 


CALL GKS$OPEN_GKS( '’SYSSERROR:’ ) 
CALL GKS$OPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240) 
CALL GKSSACTIVATE_WS( WS_ID ) 


+] CALL GKS$TEXT( START_PT_X, START_PT_Y, '’Life During Wartime’ ) 
Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 
CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_ FLAG ) 
READ (5, *) 
@ CALL GKS$SET_TEXT_HEIGHT ( THIRD _WC_POINT ) 
3] CALL GKS$CLEAR_WS( WS_ID, GKS$K_CLEAR_ALWAYS ) 


CALL GKS$TEXT( START_PT_X, START _PT_Y, ‘Life During Wartime’ ) 


CALL GKS$DEACTIVATE WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 

CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 
@ This code outputs text in the default height of 0.01 world coordinate 
units. 


@ The function SET CHARACTER HEIGHT changes the value to 0.03 
world coordinate units. 


@® This code clears the screen unconditionally. After the next call to TEXT, 
text is output to the screen at the new height. 


Figure 5-13 shows the screen of a VT241 terminal after the program has 
run to completion. 
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Text Attributes 
SET CHARACTER HEIGHT 


Figure 5-13: Changing the Text Height—VT241 
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Text Attributes 
SET CHARACTER SPACING 


SET CHARACTER SPACING 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET CHARACTER SPACING sets the current text spacing 
entry in the DEC GKS state list to the specified value. 


DEC GKS measures the spacing between characters as a fraction of the 
character height; adjusting character height automatically proportionately 
adjusts spacing. The character spacing value 0.0 places the character bodies 
next to each other without any separating space contained in the font 
specification for the letter bodies. Whether or not the characters actually 
touch depends on the type of font you are using. Positive spacing values 
increase the space between characters; negative values decrease the space. 
Using negative spacing values, it is possible to overlap characters, or to 
actually reverse the text so that characters are written in the opposite 
direction. 


GKS$SET_TEXT_SPACING (spacing_percentage) 
GSCHSP (spacing) 
gsetcharspace (spacing) 
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Text Attributes 


SET CHARACTER SPACING 
Arguments 
spacing_percentage 
data type: real 
access: read-only 
mechanism: by reference 


This argument is the character spacing factor. This value is a percentage of 
the current character height. The default for the current character spacing 
entry is the value 0.0, which displays text with adjacent character bodies. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 


must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 


routine **** 


Program Example 
| Example 5-14 illustrates the use of the function SET CHARACTER 


SPACING. Following the program example, Figure 5-14 illustrates the 
program’s effect on a VT241 workstation. 
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Text Attributes 
SET CHARACTER SPACING 


Example 5-14: Changing the Character Spacing 


Cc This program decreases the character spacing enough so that 
C the characters overlap slightly. 
IMPLICIT NONE 
INCLUDE ’ SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID 
REAL START_PT_X, START PT Y, LARGER, OVERLAP 
DATA WS_ID / 1 /, START_PT_X / 0.2 /, START PTY / 0.5 /, 
* LARGER / 0.05 /, OVERLAP / -0.3 / 


CALL GKS$OPEN_GKS( ‘SYS$ERROR:’ ) 
CALL GKSSOPEN WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE WS( WS ID ) 


1] CALL GKS$SET_TEXT_HEIGHT( LARGER ) 


2] CALL GKS$SET_TEXT_SPACING( OVERLAP ) 
CALL GKS$TEXT( START_PT_X, START _PT_Y, 
* "Relentless Cookout’ ) 


CALL GKS$DEACTIVATE WS( WS _ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ This code increases the character height so that the string is easy to see. 


@ The function SET CHARACTER SPACING changes the spacing from the 
default spacing to overlapping characters (a negative character spacing). 


These changes can occur only if the character spacing ASF is set to 
GKS$K_ASF_INDIVIDUAL (the default setting). 


Figure 5-14 shows the screen of a VT'241 terminal after the program has 
run to completion. 
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Text Attributes 
SET CHARACTER SPACING 


Figure 5-14: Changing the Character Spacing—VT241 
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Text Attributes 
SET CHARACTER UP VECTOR 


SET CHARACTER UP VECTOR 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET CHARACTER UP VECTOR sets the geometric attribute 
current character up vector entry in the DEC GKS state list to the specified 
value. DEC GKS uses this value for all subsequent calls to TEXT until you 
specify another value. 


When you call TEXT, you specify the starting point for the text. In order 

to establish an imaginary line on which to output text, you must establish 
an upward direction. Once an upward direction has been established, 

DEC GKS draws an imaginary line that is perpendicular to this upward 
direction that runs through the starting point. This perpendicular line is the 
imaginary line on which you can output text, by the positioning of the text . 
extent rectangle. . 


You specify the upward direction for character placement as a directional 
vector. The vector begins at the starting point and proceeds in the direction 
of the current character up vector entry. You establish the character up 
vector by specifying a slope for the line. 


For example, if you specify the world coordinates unit values (1.0, 1.0) 
as the character up vector, the up direction for the display of text follows 
the line passing from the starting point to the point one point above and 
one point to the right of the starting point. This would correspond to a 
45-degree angle of rotation. Specifying the values (200.0, 200.0), or the 
values (5.0, 5.0), is equivalent to specifying (1.0, 1.0). 


Figure 5-15 illustrates some of the possible values of the character up 
vector. 
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Syntax 


Text Attributes 
SET CHARACTER UP VECTOR 


Figure 5-15: Examples of Character Up Vector Entries 
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The initial value for the current character up vector entry is (0.0, 1.0), 
which orients text perpendicular to the X-axis and parallel to the Y-axis, 
if the current character path is GKS$K_TEXT_PATH_RIGHT or GKS$K_ 
TEXT_PATH_LEFT. 


GKS$SET_TEXT_UPVEC (x_vector, y_vector) 
GSCHUP (xvector, yvector) 
gsetcharup (charup) 
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Text Attributes 


SET CHARACTER UP VECTOR 
Arguments 
x_vector 
y_vector 
data type: real 
access: read-only 
mechanism: by reference 


These arguments are the X and Y unit values that establish the character 
up vector entry. Specifically, these values specify the slope of the character 


up vector. 


Error Messages 


Error Completion 

Number Status Code 

-20 DECGKS$_ERROR_NEG_20 
8 GKS$_ERROR_8 

79 GKS$_ERROR_79 


Program Example 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 
GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 

Length of character up vector is 
zero in routine **** 


Example 5—15 illustrates the use of the function SET CHARACTER UP 
VECTOR. Following the program example, Figure 5-16 illustrates the 


program’s effect on a VT241 workstation. 
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Text Attributes 
SET CHARACTER UP VECTOR 


Example 5-15: Changing the Up Character Vector 


This program shifts the default character up vector 

to the left. 

IMPLICIT NONE 

INCLUDE 'SYS$LIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID 

REAL LARGER, START _PT_X, START_PT_Y, VECTOR_X, VECTOR_Y 
DATA WS_ID / 1 /, LARGER / 0.05 /, START PT X / 0.5 /, 
* START _PT_Y / 0.5 /, VECTOR_X / -1.0 /, VECTOR_Y / 1.0 / 


CALL GKSS$OPEN_GKS( ‘SYSSERROR:’ ) 
CALL GKSSOPEN WS( WS_ID, GKS$K_CONID_ DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE_WS( WS_ID ) 


CALL GKS$SET_TEXT_UPVEC( VECTOR_X, VECTOR_Y ) 
CALL GKS$SET_TEXT HEIGHT( LARGER ) 


CALL GKS$SET_TEXT_PATH( GKS$K_TEXT_PATH LEFT ) 


CALL GKSS$TEXT( START _PT_X, START PT _Y, 

* 'John’ ) 

Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKSSUPDATE WS( WS_ID, GKSS$K_POSTPONE_FLAG ) 

READ (5, *) 


CALL GKS$SET_TEXT_PATH( GKS$K_TEXT_PATH DOWN ) 

CALL GKSSTEXT( START PT X, START PT Y, 

* 'Paul’ ) 

Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


CALL GKSSSET_TEXT PATH( GKS$K_TEXT_PATH RIGHT ) 

CALL GKS$TEXT( START _PT_X, START PT _Y, 

* 'George’ ) 

Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 





(continued on next page) 
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Text Attributes 
SET CHARACTER UP VECTOR 


Example 5—15 (Cont.): Changing the Up Character Vector 


CALL GKS$SET_TEXT_PATH( GKSS$K_TEXT PATH UP ) 
CALL GKS$TEXT( START_PT_ X, START PT_Y, 
* 'Ringo’ ) 


CALL GKSS$DEACTIVATE_WS( WS_ID ) 
CALL GKSSCLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 
@ This code alters the character up vector so that all text tilts to the left. 
@ This code increases the character height so that the string is easy to see. 
© Set the text path (in this case, to the left). 

@ Generate the text string. 


Figure 5-16 shows the screen of a VT241 terminal after the program has 
run to completion. 
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Text Attributes 
SET CHARACTER UP VECTOR 


Figure 5—16: Changing the Character Up Vector—VT241 
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Text Attributes 
SET TEXT ALIGNMENT 


SET TEXT ALIGNMENT 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET TEXT ALIGNMENT sets the current text alignment entry 
in the DEC GKS state list to a value that specifies the positioning of the text 
extent rectangle. DEC GKS uses this value for all subsequent calls to TEXT 
until you specify another value. 


Once you have determined the starting point, the text path (see SET TEXT 
PATH in this section), and the character up vector (see SET CHARACTER 
UP VECTOR in this section), you have in effect established an imaginary 
line running through the starting point, on which to output text. At 

this point, you can use SET TEXT ALIGNMENT to shift the text extent 
rectangle along this established line. 


The two arguments passed to this function establish the horizontal and 
vertical position of the text extent rectangle on the imaginary text line. 
For example, you can position the text extent rectangle horizontally so the 
starting point is to the left, in the center, or to the right of the text extent 
rectangle. 


Not only can you position the text extent rectangle horizontally along the 
imaginary text line, you can position the rectangle vertically along the same 
line. For example, you can position the text extent rectangle so that the 
starting point is aligned with the top of the characters in the string, with 
the cap of the characters, with the half line of the characters, with the base 
line of the characters, or with the bottom line of the characters. 


Figure 5-17 illustrates how you can align the text extent rectangle 
horizontally and vertically. The text path is from right to left and the 
imaginary text line is illustrated as a dashed line. 


5-84 Output Attribute Functions 


Text Attributes 
SET TEXT ALIGNMENT 


Figure 5-17: Horizontal and Vertical Text Alignment 
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The default horizontal and vertical alignments depend on the text path, 
and can be explicitly passed using the arguments GKS$K_TEXT_HALIGN_ 
NORMAL and GKS$K_TEXT_VALIGN_NORMAL. Figure 5-18 shows the 
default values for each of the four text paths. 


Figure 5-18: Default Horizontal and Vertical Text Alignments 
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For more information concerning the text extent rectangle or character 
output in general, refer to the DEC GKS User Manual. 
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Syntax 

GKS$SET_TEXT_ALIGN (horizontal, vertical) 

GSTXAL §(halign, valign) 

gsettextalign  (ixalign) 
Arguments 

horizontal 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the horizontal alignment for text output. The argument 
can be any of the following values or constants. 


Value Constant Description 
0 GKS$K_TEXT_HALIGN_NORMAL Normal 

1 GKS$K_TEXT_HALIGN_LEFT Left 

2 GKS$K_TEXT_HALIGN_CENTER — Center 

3 GKS$K_TEXT_HALIGN_RIGHT Right 


For more information on the use of these values and constants, refer to 
Figures 5-17 and 5-18. 


vertical 

data type: integer 
access: read-only 
mechanism: by reference 


This argument is the vertical alignment for text output. The argument can 
be any of the following values or constants. 
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Value Constant Description 
0 GKS$K_TEXT_VALIGN_.NORMAL Normal 
1 GKS$K_TEXT_VALIGN_TOP Top 
2 GKS$K_TEXT_VALIGN_CAP Cap 
3 GKS$K_TEXT_VALIGN_HALF Half 
4 GKS$K_TEXT_VALIGN_BASE Base 
5 GKS$K_TEXT_VALIGN_BOTTOM Bottom 


For more information on the use of these values and constants, refer to 
Figures 5-17 and 5-18. 


Error Messages 


Error Completion 
Number Status Code Message 
-12 DECGKS$_ERROR_NEG_12 Invalid value specified for horizon- 


tal component of text alignment in 
routine **** 


-13 DECGKS$_ERROR_NEG_13 Invalid value specified for vertical 
component of text alignment in 
routine **** 


—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 
8 GKS$_ERROR_8 GKS not in proper state: GKS 


must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


Program Example 


Example 5-16 illustrates the use of the function SET TEXT ALIGNMENT. 
Following the program example, Figure 5-19 illustrates the program’s effect 
on a VT241 workstation. 


5-88 Output Attribute Functions 


Text Attributes 
SET TEXT ALIGNMENT 


Example 5-16: Changing the Text Alignment 





This program writes a string to the workstation using the 
normal text alignments for each of the text paths. 
IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS _ID, ONE _PMARK, RED 

REAL LARGER, START PT X, START PT Y 

DATA WS_ID / 1 /, ONE_PMARK / 1 /, LARGER / 0.07 /, 

* START_PT X / 0.5 /, START PT Y / 0.5 /, RED / 2 / 


CALL GKSSOPEN_GKS( ‘’SYSSERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKSS$K_CONID_ DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE WS( WS_ID ) 


CALL GKSS$SET_TEXT_HEIGHT( LARGER ) 


CALL GKS$SET_PMARK_COLOR_INDEX( RED ) 
CALL GKS$SET_PMARK TYPE( GKS$K_MARKERTYPE PLUS ) 


CALL GKS$SET_TEXT PATH( GKS$K_TEXT PATH RIGHT ) 
CALL GKS$SET_TEXT ALIGN( GKS$K_TEXT HALIGN NORMAL, 

* GKSS$K_TEXT VALIGN NORMAL ) 

CALL GKS$TEXT( START PT X, START PTY, ‘TEXT’ ) 

CALL GKS$POLYMARKER( ONE_PMARK, START_PT_X, START PTY ) 


Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


CALL GKS$SET_TEXT_PATH( GKS$K_TEXT_PATH LEFT ) 

CALL GKS$SET_TEXT_ALIGN( GKS$K_TEXT_HALIGN_NORMAL, 

* GKSS$K_TEXT_VALIGN_ NORMAL )_ 

CALL GKS$TEXT( START_PT_X, START _PT_Y, ‘TEXT’ ) 

CALL GKS$POLYMARKER( ONE_PMARK, START_PT_X, START_PT_Y ) 


Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKSSUPDATE WS( WS_ID, GKSSK_POSTPONE_ FLAG ) 

READ (5, *) 


CALL GKS$SET_TEXT PATH( GKS$K_TEXT PATH UP ) 

CALL GKS$SET TEXT ALIGN( GKS$K_TEXT HALIGN NORMAL, 

* GKSS$K_TEXT VALIGN NORMAL ) 

CALL GKS$TEXT( START PT X, START PT Y, ‘TEXT’ ) 

CALL GKS$POLYMARKER( ONE _PMARK, START_PT_X, START_PT Y ) 


(continued on next page) 


Output Attribute Functions 5-89: 


Text Attributes 
SET TEXT ALIGNMENT 


5-90 


Example 5-16 (Cont.): Changing the Text Alignment 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 
CALL GKS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 
READ (5, *) 
6] CALL GKS$SET_TEXT_PATH( GKS$K_TEXT_PATH_DOWN ) 


CALL GKSS$SET_ TEXT ALIGN( GKS$K_TEXT HALIGN NORMAL, 

* GKS$K_TEXT_VALIGN NORMAL ) 

CALL GKSS$TEXT( START _PT_X, START PT Y, ‘TEXT’ ) 

CALL GKS$POLYMARKER( ONE _PMARK, START PT X, START PT Y ) 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ This code increases the character height so that the string is easy to see. 


@ This code sets the polymarker color and type. A red plus sign marks the 
text starting point. 


© Set the text path to GKS$K_TEXT_PATH_RIGHT. Notice that the 
normal alignment for this path includes horizontal alignment of the 
starting point to the left and vertical alignment along the base of the 
letters. 


© Set the text path to GKS$K_TEXT_PATH_ LEFT. Notice that the normal 
alignment for this path includes horizontal alignment of the starting 
point to the right and vertical alignment along the base of the letters. 


© Set the text path to GKS$K_TEXT_PATH_UP. Notice that the normal 
alignment for this path includes horizontal alignment of the starting 
point to the center and vertical alignment along the base of the first 
letter. 

© Set the text path to GKS$K_TEXT_PATH_ DOWN. Notice that the 
normal alignment for this path includes horizontal alignment to the 
center and vertical alignment along the top of the first letter. 
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Figure 5-19 shows the screen of a VT241 terminal after the program has 
run to completion. The text is in green and the plus sign is red. 


Figure 5-19: Changing the Text Alignment—VT241 
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SET TEXT COLOR INDEX 


. Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET TEXT COLOR INDEX sets the current text color index 
entry in the DEC GKS state list to the specified value. 


Syntax 
GKS$SET_TEXT_COLOR_INDEX (color_index) 
GSTXCI (cindex) 
gsettextcolourind (index) 
Arguments 
color_index 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the text color index. The default value for the text color 
index entry is the value 1, which designates the default foreground color. 
For more information concerning predefined color indexes, refer to the DEC 
GKS Device Specifics Reference Manual. 
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Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
8 GKS$_ERROR_8 

92 GKS$_ERROR_92 


Program Example 


Text Attributes 
SET TEXT COLOR INDEX 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 
GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 

Color index is less than zero in 
routine **** 


Example 5-17 illustrates the use of the function SET TEXT COLOR INDEX. 
Following the program example, Figure 5-20 illustrates the program’s effect 


on a VT241 workstation. 
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Example 5-17: Changing the Text Color Index 


Cc This program produces a blue text string. 
IMPLICIT NONE 
INCLUDE ’SYSS$LIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, BLUE 


REAL 
DATA 


LARGER, START PT X, START PT Y 
WS_ID / 1 /, LARGER / 0.07 /, BLUE / 3 /, 


* START PT X / 0.5 /, START PT Y / 0.5 / 


CALL 
CALL 
CALL 


0 CALL 
@ CALL 


CALL 


CALL 
CALL 
CALL 
END 


GKSSOPEN_GKS( ’SYS$ERROR:’ ) 
GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240) 
GKSS$ACTIVATE WS( WS_ID ) 


GKS$SET_TEXT_HEIGHT( LARGER ) 


GKS$SET_TEXT_COLOR_INDEX( BLUE ) 
GKS$TEXT( START PT X, START PT Y, ‘TEXT’ ) 


GKSS$DEACTIVATE_WS( WS_ID ) 
GKS$CLOSE_WS( WS_ID ) 
GKS$CLOSE_GKS () 


The following numbers correspond to the numbers in the previous example: 


@ This code increases the character height so that the string is easy to see. 


@ The function, SET TEXT COLOR INDEX, changes the color from the 
default color to blue, but only if the text color ASF is set to GKS$K_ 
ASF_INDIVIDUAL (the default setting). 


The VT241 predefines the color index value 3 to be blue. Workstations 
other than the VT241 may predefine a different representation of color 
index 3 (a color other than blue). 


Figure 5-20 shows the screen of a VT241 terminal after the program has 
run to completion. The text changed from the default color green to the color 


blue. 
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Figure 5-20: Changing the Text Color Index—VT241 
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SET TEXT FONT AND PRECISION 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET TEXT FONT AND PRECISION sets the current text font 
and precision entry in the DEC GKS state list to the specified value. 


When using this function, the types of fonts available for use depend on 
which precision value you pass as an argument. The values, in order of 
increasing precision, are as follows: 


e String (GKS$K_TEXT_PRECISION_STRING) 
e Character (GKS$K_TEXT_PRECISION_CHAR) 
e Stroke (GKS$K_TEXT_PRECISION_STROKE) 


As the precision increases, the precision of clipping, character size, characte: 
spacing, character expansion factor, and the character up vector all improve. 


If you specify string precision, and if you specify a starting position for the 
string that is located outside of the current normalization viewport, the call 
to SET TEXT FONT AND PRECISION causes the entire text string to be 
clipped. If the starting point for the string is located inside of the current 
normalization viewport, this function may cause the string to be clipped by 
character or by stroke depending on the capabilities of the workstation. If 
you require string precison, you cannot use the DEC GKS software fonts; 
you can only specify the numbers of the device-dependent fonts available on 
your particular workstation. For more information concerning the device- 
dependent fonts available on a workstation, refer to the DEC GKS Device 
Specifics Reference Manual. 


If you specify character precision, the call to SET TEXT FONT AND 
PRECISION causes the text string to be clipped at the current normalizatior 
viewport on a character-by-character basis. If you require character 
precison, you cannot use the DEC GKS software fonts; you can only specify 
the numbers of the device-dependent fonts available on your particular 
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SET TEXT FONT AND PRECISION 


workstation. For more information concerning the fonts available on a 
workstation, refer to the DEC GKS Device Specifics Reference Manual. 


If you specify stroke precision, the call to SET TEXT FONT AND 
PRECISION causes the text string to be clipped exactly at the current 
normalization viewport. This is the highest precision. When using this pre- 
cision, you may make use of the device-independent fonts that are available 
on all workstations. For a description of each of these available software 
fonts and their values, refer to Appendix G, DEC GKS Device-Independent 
Fonts. 


Be aware that all images are clipped at the current workstation window. For 
more information concerning clipping, refer to Chapter 6, Transformation 
Functions. 


Together, text font and precision specify the display quality of text and the 
speed at which the text is displayed. Typically, use of a software font in 
stroke precision produces higher-quality character symbols than use of a 
hardware font in either character or string precision. However, character 
and string precision use the workstation character generator, if available, 

to display text and thus produce the images somewhat faster than stroke 
precision. Also, since character and string precision are less precise in the 
application of the other text attributes (for example, height and width), they 
require less calculation to represent each character in a text string. 


The default value for the current text font and precision entry specifies the 
hardware font value, 1, and string precision. 


GKS$SET_TEXT FONTPREC (font_value, precision_value) 
GSTXFP (font, precision) 
gsettextfontprec  (ixfp) 


Output Attribute Functions 5~97 


Text Attributes 
SET TEXT FONT AND PRECISION 


Arguments | 
font_value 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the font value. If you are using the character or string 
precisions, refer to the DEC GKS Device Specifics Reference Manual for 
more information. If using stroke precision, refer to Appendix G, DEC GKS 
Device-Independent Fonts in this manual. 


precision_value 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the precision value. See the function description for 
detailed information concerning these values. The argument can be any of 
the following values or constants: 


Value Constant Description 

0 GKS$K_TEXT_PRECISION_STRING Lowest precision 

1 GKS$K_TEXT_PRECISION_CHAR Moderate precision 

2 GKS$K_TEXT_PRECISION_ Highest precision 
STROKE 
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Error 
Number 


-14 


—20 


32 


75 


Program Example 


Text Attributes 


SET TEXT FONT AND PRECISION 


Completion 
Status Code 
DECGKS$_ERROR_NEG_14 
DECGKS$_ERROR_NEG_20 


DECGKS$_ERROR_NEG_32 


GKS$_ERROR_8 


GKS$_ERROR_75 


Message 


Invalid value specified for text 
precision in routine **** 


GKS not in proper state: GKS in 
the error state in routine **** 


Font file for stroke precision text 


not found or unusable in routine 
KEK 


GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


Text font is equal to zero in 
routine **** 


Example 5-18 illustrates the use of the function SET TEXT FONT AND 
PRECISION. Following the program example, Figure 5—21 illustrates the 


program’s effect on a VT241 workstation. 
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Example 5-18: Changing the Text Font and Precision 


Cc This program changes the default font and precision to 
Cc stroke/Old English (Large Gothic Triplex English). 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, OLD ENGLISH 
REAL START_PT X, START PT _Y, LARGER 
DATA WS_ID / 1 /, START PT X / 0.01 /, START_PT_Y / 0.5 /, 
* LARGER / 0.05 /, OLD_ENGLISH / -18 / 


CALL GKSSOPEN_GKS ( ’SYSSERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240) 
CALL GKSSACTIVATE WS( WS_ID ) 


0 CALL GKS$SET_TEXT HEIGHT( LARGER ) 


CALL GKS$SET_TEXT FONTPREC( OLD_ENGLISH, 
* GKSS$K_TEXT PRECISION STROKE ) 

CALL GKS$TEXT( START PT X, START PT Y, 
* 'THE MORAL KIOSK’ ) 


CALL GKSSDEACTIVATE_WS( WS_ID ) 
CALL GKSS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ This code increases the character height so that the string is easy to see. 


@ The function, SET TEXT FONT AND PRECISION, changes the font 
from the hardware font 1, to the Old English (Large Gothic Triplex 
English) software font -18. SET TEXT FONT AND PRECISION 
also changes the precision from string to stroke. These changes can 
only occur if the text font and precision ASF is set to GKS$K_ASF_ 
INDIVIDUAL (the default setting). 


Figure 5-21 shows the screen of a VT241 terminal after the program has 
run to completion. 
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Figure 5-21: Changing the Text Font and Precision 
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SET TEXT INDEX 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET TEXT INDEX establishes the index value pointing into 
the text bundle table. The text bundle table contains entries for the text 
font and precision, character expansion factor, character spacing, and text 
color index attribute values. When calling TEXT, DEC GKS uses the bundle 
table only if the corresponding attribute source flag has been set to 
GKS$K_ASF_BUNDLED. 


For a list of the available text bundles for each workstation, refer to the 
DEC GKS Device Specifics Reference Manual. 


Syntax 
GKS$SET_TEXT_INDEX (index) 
GSTXI  (tindex) 
gsetiextind (index) 
Arguments 
index 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the text bundle index. The default bundle index is the 
value 1. For more information concerning predefined text bundle table 
indexes, refer to the DEC GKS Device Specifics Reference Manual. 
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Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
8 GKS$_ERROR_8 

72 GKS$_ERROR_72 


Program Example 


Text Attributes 
SET TEXT INDEX 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 
GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** 


- Text index is invalid in routine 


KKK 


Example 5-19 illustrates the use of the function SET TEXT INDEX. 
Following the program example, Figure 5—22 illustrates the program’s effect 


on a VT241 workstation. 
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Example 5-19: Changing the Text Index 





aaa 


200 


This program sets the Attribute Source Flags (ASFs) to bundled, 
and then displays the effects of using the six index values 
in calls to GKS$SET_TEXT_INDEX. 

IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, FLAGS( 13 ), INCR 

REAL START PT X, START PT _Y, LARGER 

DATA WS_ID / 1 /, START PT X / 0.1 /, START PT Y / 0.5 /, 

* LARGER / 0.03 / 

CHARACTER*2 STR 

CALL GKSSOPEN_GKS( 'SYSSERROR:’ ) 

CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240) 
CALL GKSSACTIVATE_WS( WS_ID ) 


FLAGS( 7 ) = GKS$K_ASF_BUNDLED 
FLAGS( 8 ) = GKS$K_ASF_BUNDLED 
FLAGS( 9 ) = GKS$K_ASF_BUNDLED 


FLAGS( 10 ) = GKS$K_ASF_BUNDLED 
CALL GKS$SET_ASF( FLAGS ) 


CALL GKS$SET_TEXT_HEIGHT( LARGER ) 


DO 200 INCR = 1, 6,'1 

CALL GKS$CLEAR_WS( WS_ID, GKS$K_CLEAR_ALWAYS ) 
CALL GKS$SET_TEXT_INDEX( INCR ) 

CALL GKS$TEXT( START PT X, START PTY, 

* ‘Family of Max Desir’ ) 


CALL LIB$CVT_DX _DX( %SDESCR( INCR ), %DESCR( STR ) ) 

CALL GKS$TEXT( .1, .3, ’Index: ’) 

CALL GKSSTEXT( .4, .3, %DESCR( STR ) ) 

Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_ FLAG ) 

READ (5, *) 


CONTINUE 


CALL GKSSDEACTIVATE WS( WS_ID ) 
CALL GKSS$CLOSE_WS( WS_ID ) 

CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example. 


@ This code initializes the elements of the array that affect all the nongeo- 


metric polymarker attributes. This code sets each ASF to GKS$K_ASF_ 
BUNDLED. The parameter flags( 7 ) corresponds to the text font and 
precision, flags( 8 ) corresponds to the character expansion factor, 
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flags( 9 ) corresponds to the character spacing, and flags( 10 ) corre- 
sponds to the text color index. 


See the SET ASPECT SOURCE FLAGS function description in this 
chapter for more information. 


@ This code displays the text using the six text index values available on 
the VT241. This code writes the index value that produced the text, in 
the lower left portion of the screen. 


© This VMS Run-Time Library Routine translates the variable INCR to a 
text string so that TEXT can write the text index value to the screen. 


Figure 5-22 shows the screen of a VT241 terminal after the program has 
run to completion. The color of the text is blue. 


Figure 5-22: Changing the Text Index—VT241 
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SET TEXT PATH 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET TEXT PATH sets the geometric attribute current text path 
entry in the DEC GKS state list to be the writing direction for the display 
of text. DEC GKS uses this value for all subsequent calls to TEXT until you 
specify another value. 


Once you have determined the starting point and the character up vector 
(see SET CHARACTER UP VECTOR in this section), you have in effect 
established an imaginary line running through the starting point to use 
when generating text primitives. You can output your text string with your 
aligned letter starting at the starting point (see SET TEXT ALIGNMENT 
in this section). According to the current text path, the string either reads 
to the right along the imaginary line (the default), to the left along the 
imaginary line, upwards in a perpendicular direction from the imaginary 
line, or downwards in a perpendicular direction from the imaginary text 
line. 


If using the default text alignment (see SET TEXT ALIGNMENT), DEC 
GKS places the first letter of this string at the starting point, and sub- 
sequent letters are written along the imaginary text line in the direction 
specified by a call to this function. The default text path is left to right along 
the imaginary text line (GKS$K_TEXT_PATH_RIGHT). 


Figure 5—23 illustrates the writing direction for each value of text path. The 
figure assumes (0.0, 1.0) as the character up vector. 
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Figure 5-23: Text Path Directions 
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Syntax 


GKS$SET_TEXT_PATH (text_path) 
GSTXP  (text_path) 
gsettextpath (text_path) 
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Arguments 


text_path 


data type: 
access: 


mechanism: 


integer 
read-only 
by reference 


This argument is the text path. The argument can be any of the following 
values or constants: 


Value Constant 

0 GKS$K_TEXT_PATH_RIGHT 

1 GKS$K_TEXT_PATH_LEFT | 
2 GKS$K_TEXT_PATH_UP 

3 GKS$K_TEXT_PATH_DOWN 


Error Messages 


Error 
Number 


-15 


Completion 
Status Code 


DECGKS$_ERROR_NEG_15 
DECGKS$_ERROR_NEG_20 


GKS$_ERROR_8 
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Description 


Left to right 
Right to left 
Bottom to top 
Top to bottom 


Message 


Invalid value specified for text 
path in routine *** 

GKS not in proper state: GKS in 
the error state in routine **** 
GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 
routine **** . 


Program 


oh) 


Text Attributes 
SET TEXT PATH 


Example 


Example 5-20 illustrates the use of the function SET TEXT PATH. 
Following the program example, Figure 5—24 illustrates the program’s effect 
on a VT241 workstation. 


Example 5-20: Changing the Text Path 


Cc This program shows each of the four text paths. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID 
REAL LARGER, START PT _X, START PT Y 
DATA WS_ID / 1 /, LARGER / 0.05 /, 
* START PT X / 0.5 /, START_PT_Y / 0.5 / 


CALL GKSSOPEN_GKS( 'SYS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSS$ACTIVATE_WS( WS ID ) 


CALL GKS$SET_TEXT_HEIGHT( LARGER ) 


CALL GKS$SET_TEXT PATH( GKS$K_TEXT_PATH_LEFT ) 

CALL GKS$TEXT( START _PT_X, START PT Y, 

* ‘Burning’ ) 
Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 

CALL GKS$SET_TEXT_PATH( GKS$K_TEXT_PATH DOWN ) 

CALL GKSS$TEXT( START_PT _X, START PT Y, 

* ‘Down’ ) 
Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_ FLAG ) 

READ (5, *) 


(continued on next page) 
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Example 5-20 (Cont.): Changing the Text Path 


CALL GKS$SET_TEXT PATH( GKS$K_TEXT PATH RIGHT ) 
CALL GKS$TEXT( START PT X, START PT Y, 


* 'The’ ) 
Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


CALL GKSSSET_TEXT_PATH( GKS$K_TEXT PATH UP ) 
CALL GKSSTEXT( START_PT_X, START _PT Y, 
* ‘House’ ) 


CALL GKSS$DEACTIVATE_WS( WS_ID ) 
CALL GKSS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ This code increases the character height so that the string is easy to see. 
@ Set the text path (in this case, to the left). 
© Output the text string. 


Figure 5-24 shows the screen of a VT241 terminal after the program has 
run to completion. 
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Figure 5-24: Changing the Text Path—VT241 
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Aspect Source Flag Function 


This section describes the aspect source flags (ASFs), which are nongeomet- 
ric attributes. 
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SET ASPECT SOURCE FLAGS 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET ASPECT SOURCE FLAGS specifies to DEC GKS whether 
to use the bundled or the individual method for designating each of the 
nongeometric output attributes. 


There are thirteen nongeometric attribute source flags (ASF), numbered 

1 to 13. You pass an array with thirteen elements to SET ASPECT 
SOURCE FLAGS. If the value in the corresponding element is GKS$K_ 
ASF_INDIVIDUAL, DEC GKS uses the individual attribute setting. If the 
value in the corresponding element is GKS$K_ASF_BUNDLED, DEC GKS 
uses the bundle table index to find the attribute setting. 


The initial value for each ASF is individual, which causes the output 
functions to use the current individual value for each nongeometric 
attribute. Remember that when specified individually, attributes are 
workstation independent; when specified as a bundle, the attributes are 
workstation dependent. For instance, most workstations provide a fill 
area bundle index 1, but the resulting fill area can look different on each 
workstation. For more information concerning the bundle table indexes 
available for your workstation, refer to the DEC GKS Device Specifics 
Reference Manual. 


GKS$SET_ASF (flags) 
GSASF (flags) 
gsetasf (asfs) 


Output Attribute Functions 5-113 


Aspect Source Flag Function 


SET ASPECT SOURCE FLAGS 
Arguments 
flags 
data type: array (integer) 
access: read-only 
mechanism: by reference 


This argument is the array of the thirteen attribute source flags (ASFs). 
There exists one element for each of the nongeometric output attributes, as 


follows: 


Number Nongeometric Attribute 
Line type 

Line width scale factor 
Polyline color index 
Marker type 

Marker size scale factor 
Polymarker color index 
Text font and precision 


Character expansion factor 


oon aa» rr WN FE 


Character spacing 


— 
oO 


Text color index 


— 
_ 


Fill area interior style 


a 
bo 


Fill area style index 


— 
is) 


Fill area color index 
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Error Messages 
Error Completion 
Number Status Code 
—10 DECGKS$_ERROR_NEG_10 
—20 DECGKS$_ERROR_NEG_20 
8 GKS$_ERROR_8 


Program Example 


SET ASPECT SOURCE FLAGS 


Message 


Invalid value specified for ASF in 
routine **** 

GKS not in proper state: GKS in 
the error state in routine **** 
GKS not in proper state: GKS 
must be in one of the states 
GKOP, WSOP, WSAC, or SGOP in 


routine **** 


Refer to Example 5—7 in this chapter for a program example using a call to 


SET ASPECT SOURCE FLAGS. 
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Representation Functions 


The DEC GKS functions described in this section define or change the 
nongeometric attributes associated with a given bundle table index. These 
attributes comprise the index’s representation. Bundle representations are 
unique to each workstation (device dependent). 


Notice that DEC GKS must be in the GKS$K_WSOP state in order for you 
to call these functions. For more information concerning operating states, 
refer to Chapter 3, Control Functions. 


A list of the different nongeometric representation types follows: 


Color representation 

Fill representation 
Pattern representation 
Polyline representation 
Polymarker representation 
Text representation 
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SET COLOR REPRESENTATION 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET COLOR REPRESENTATION allows you to redefine 

an existing color index representation, or to define a new representation, 
by specifying the red, green, and blue color intensities associated with a 
specified bundle index. The workstation maps the color you specify to the 
nearest available color the workstation can produce. 


All workstations define default color table entry indexes 0 and 1. By 
default, the value 0 corresponds to the default background color (the color 
of an empty display surface), and the value 1 corresponds to the default 
foreground color. Also by default, the values greater than the value 1 
correspond to alternative foreground colors. 


Depending on the capabilities of your workstation, a call to this function 
may cause DEC GKS to implicitly regenerate the workstation surface. For 
information concerning implicit regeneration, refer to Chapter 3, Control 
Functions. 


Attribute values passed to this function must be valid for the specified 
workstation. For information, refer to the DEC GKS Device Specifics 
Reference Manual. 


GKS$SET_COLOR_REP (worksiation_id, color_index, 
red_intensity, green_intensity, 
blue_intensity) 


GSCR_ (workstation_id, cindex, red_i, green_i, blue_i) 
gsetcolourrep (workstation_id, index, rep) 
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Arguments 


workstation_id 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in Chapter 3, Control Functions). 


color_index 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the color index value. By specifying a value to this 
function, you are redefining the associated color by specifying a blend of red, 
green, and blue intensities previously associated with this color index. 


red_intensity 
green_intensity 
blue_intensity 


data type: real 
access: read-only 
mechanism: by reference 


These arguments are the red, green, and blue intensities that form the 
desired color. RGB values must fall within the range 0.0 to 1.0, or DEC GKS 
generates an error. For more information concerning these intensities, refer 
to the DEC GKS Device Specifics Reference Manual. 


5-118 Output Attribute Functions 


Error Messages 


20 
25 
33 
35 


36 


93 


96 


Program Example 


Representation Functions 


SET COLOR REPRESENTATION 


Completion 
Status Code 


DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_33 
GKS$_ERROR_35 


GKS$_ERROR_36 


GKS$_ERROR_93 


GKS$_ERROR_96 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 

Specified workstation is not open 
in routine **** 

Specified workstation is of cate- 
gory MI in routine **** 

Specified workstation is of cate- 
gory INPUT in routine **** 


Specified workstation is 
Workstation Independent Segment 
Storage in routine **** 

Color index is invalid in routine 
RK 

Color is outside range [0,1] in 
routine **** 


Example 5-21 illustrates the use of the function SET COLOR 
REPRESENTATION. Following the program example, Figure 5-25 
illustrates the program’s effect on a VT241 workstation. 
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Example 5-21: Changing the Color Representation 


3) 


This program changes the fill color of a triangle from 

the color blue to the color pink. 

IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, BLUE, NUM_POINTS 

REAL PX( 3 ), PY( 3 ), RED_INTENS, GREEN_INTENS, BLUE_INTENS 
DATA WS_ID / 1 /, BLUE / 3 ~/, NUM | POINTS fp OTs 


* RED_INTENS / 0.6258 /, GREEN_INTENS / 0.2142 /, 
* BLUE _INTENS / 0.2142 / 


CALL GKSSOPEN_GKS( ’SYSS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE WS( WS_ID ) 


DATA PX /.1, .9, .1/ 
DATA PY /.1, .9, .9/ 


CALL GKS$SET_FILL COLOR_INDEX( BLUE ) 

CALL GKSS$SET | FILL _ INT_STYLE( GKS$K_INTSTYLE SOLID " 

CALL GKSS$FILL_AREA ( NUM_POINTS, PX, PY ) 

Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKSSUPDATE WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


CALL GKS$SET_COLOR_REP( WS_ID, BLUE, 


* RED _INTENS, GREEN_INTENS, BLUE_INTENS ) 


CALL GKSSDEACTIVATE WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 

CALL GKS$CLOSE | __GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ PX contains the polygon’s X world coordinate values and PY contains the 


Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .1). 


The function, SET FILL AREA COLOR INDEX, changes the color from 
the default color to blue. By default, the fill area color ASF is set to 
GKS$K_ASF_INDIVIDUAL. 


Workstations other than the VT241 may predefine a different represen- 
tation of color index 3 (a color other than blue). . 


As soon as you call SET COLOR REPRESENTATION, DEC GKS 
dynamically changes the blue triangle to a pink triangle. 
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Other workstations may not be able to dynamically alter the workstation 
surface, and may need to implicitly regenerate the surface to make 

a change to a color table entry. For information concerning implicit 
regenerations, refer to Chapter 3, Control Functions. 


Figure 5-25 shows the screen of the VT241 terminal after the program has 
run to completion. 


Figure 5-25: Changing the Color Representation—VT241 
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SET FILL AREA REPRESENTATION 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET FILL AREA REPRESENTATION allows you to redefine 
an existing fill area bundle table index representation, or to define a new fill 
area bundle table index value, by specifying the fill area interior style, fill 
area style index value, and fill area color index associated with the specified 
bundle index. 


Depending on the capabilities of your workstation, a call to this function 
may cause DEC GKS to implicitly regenerate the workstation surface. For 
information concerning implicit regeneration, refer to Chapter 3, Control 
Functions. 


Attribute values passed to this function must be valid for the specified 
workstation. For information, refer to the DEC GKS Device Specifics 
Reference Manual. 


GKS$SET_FILL_REP (workstation_id, fill_index, interior_style, 
style_index, color_index) 


GSFAR_ (workstation_id, index, style, sindex, cindex) 
gsetfillrep (workstation_id, index, rep) 


5-122 Output Attribute Functions 


) Representation Functions 
SET FILL AREA REPRESENTATION 


Arguments 


workstation_id 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in Chapter 3, Control Functions). 


fill_index 

data type: integer 
access: -  yead-only 
mechanism: by reference 


This argument is the fill area bundle table index value. By specifying a 
value to this function, you are redefining the interior style, style index, and 
color index entries in the associated bundle table. See SET FILL AREA 
INDEX in this section for more information. 


interior_style 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the interior style index value to be associated with the 
specified fill area index value. The argument can be any of the following 
values or constants: 


Value Constant Description _ 

0 GKS$K_INTSTYLE_HOLLOW Use an outline. 

1 GKS$K_INTSTYLE_SOLID Use color. 

2 GKS$K_INTSTYLE_PATTERN Use a pattern. 

3 GKS$K_INTSTYLE_HATCH Use crossed or parallel lines. 


See SET FILL AREA INTERIOR STYLE in this section for more 
information. 
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style_index 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the fill area style index. If you specified hollow or solid 
for the interior style argument, DEC GKS ignores this argument. For more 
information concerning the possible fill area style indexes, refer to the DEC 
GKS Device Specifics Reference Manual. 


color_index 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the fill area color index. For more information concerning 
the possible fill area color indexes, refer to the DEC GKS Device Specifics 
Reference Manual. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 

20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 

25 GKS$_ERROR_25 Specified workstation is not open 
in routine **** 

33 GKS$_ERROR_33 Specified workstation is of cate- 


gory MI in routine **** 
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Error 
Number 


35 


36 


80 


83 


85 


86 


93 


Program Example 


Completion 
Status Code 


GKS$_ERROR_35 


GKS$_ERROR_36 


GKS$_ERROR_80 


GKS$_ERROR_83 


GKS$_ERROR_85 


GKS$_ERROR_86 


~ GKS$_ERROR_93 
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Message 


Specified workstation is of cate- 
gory INPUT in routine **** 


Specified workstation is 
Workstation Independent Segment 
Storage in routine **** — 


Fill area index is invalid in routine 
KR 


Specified fill area interior style is 
not supported on this workstation 
in routine **** 


Specified pattern index is invalid | 
in routine **** 


Specified hatch style is not sup- 
ported on this workstation in 
routine **** 


Color index is invalid in routine 
KKK 


Example 5-22 illustrates the use of the function SET FILL AREA 
REPRESENTATION. Following the program example, Figure 5—26 
illustrates the program’s effect on a VT241 workstation. 
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Example 5—22: Changing the Fill Area Representation 


aqaaqagana 


This program sets the Attribute Source Flags (ASFs) to bundled, 
shows the fill area corresponding to the index 2, and then 
changes the attributes associated with fill area index 2, using 
GKS$SET_FILL_REP. 

IMPLICIT NONE 

INCLUDE ‘’SYSS$LIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, BLUE, NUM_POINTS, FILL_INDEX, 

* VERT_LINES, FLAGS( 13 ), SEG NAME 

DATA WS_ID / 1 /, NUM_POINTS / 3 /, FILL_INDEX / 2 /, 

* VERT LINES / -5 /, BLUE / 3 /, SEG_NAME / 1 / 


DATA PX /.1, .9, .1/ 
DATA PY /.1, .9, .9/ 
REAL PX( 3 ), PY( 3 ) 


CALL GKS$OPEN_GKS( 'SYS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


FLAGS( 11 ) = GKS$K_ASF_BUNDLED 
FLAGS( 12 ) = GKS$K_ASF BUNDLED 
FLAGS( 13 ) = GKS$K_ASF BUNDLED 
CALL GKS$SET_ASF( FLAGS ) 


Put all output in a segment. 
CALL GKS$CREATE_SEG( SEG NAME ) 


CALL GKS$SET_FILL INDEX( FILL_INDEX ) 


CALL GKS$FILL_AREA( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG() 


Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


CALL GKS$SET_FILL_REP( WS_ID, FILL_INDEX, 
* GKSS$K_INTSTYLE_HATCH, VERT_LINES, BLUE ) 


Cause a regeneration of the screen to see the change on a VT24l1. 
CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM_FLAG ) 





(continued on next page) 
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Example 5—22 (Cont.): Changing the Fill Area Representation 


CALL GKSSDEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


PX contains the polygon’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .1). 

This code initializes the elements of the array that affect all the nonge- 
ometric fill area attributes. This code sets each ASF to GKS$K_ASF_ 
BUNDLED. The parameter flags( 11 ) corresponds to the current fill area 
interior style, flags( 12 ) corresponds to the current fill area style index, 
and flags( 13 ) corresponds to the fill area color index. 


See the SET ASPECT SOURCE FLAGS function description in this 
chapter for more information. 


© On a VT241, setting the fill area bundle table index to the value 2 


specifies a fill area that is solid red. 


On a VT241, calling SET FILL AREA REPRESENTATION causes an 
implicit regeneration that is suppressed by the workstation (by default). 
The attribute changes are not made and the screen is out of date. You 
need to call UPDATE WORKSTATION to update the surface of the 
workstation. 


If your workstation requires an implicit regeneration to implement 
changes to fill area representation but does not suppress the regener- 
ation by default, the workstation redraws only the visible segments on 
the workstation surface. Output primitives not contained in segments 
are lost. For a complete discussion of implicit regeneration, refer to 
Chapter 3, Control Functions. 
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Figure 5-26 shows the VT241 surface after the program was executed. The 
color of the triangle changed from red to blue. 


Figure 5-26: Changing the Fill Area Representation—VT241 
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SET PATTERN REPRESENTATION 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET PATTERN REPRESENTATION allows you to redefine 
an existing pattern bundle table index representation, or to define a new 
pattern bundle table index value, by specifying the number of cells high, 
the number of cells wide, and an array containing each cell’s color index fill 
area, associated with the specified bundle index. 


Depending on the capabilities of your workstation, a call to this function 
may cause DEC GKS to implicitly regenerate the workstation surface. For 
information concerning implicit regeneration, refer to Chapter 3, Control 
Functions. 


Attribute values passed to this function must be valid for the specified 
workstation. For information, refer to the DEC GKS Device Specifics 
Reference Manual. 


GKS$SET_PAT_REP (workstation_id, pattern_index, 
offset_column_number, 
offset_row_number, num_columns, 
num_rows, color_index_array) 


GSPAR_  (workstation_id, pindex, dim_x, dim_y, scol, srow, ncols, 
nrows, cindex) 


gsetpatrep (workstation_id, index, rep) 
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Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in Chapter 3, Control Functions). 


pattern_index 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the pattern bundle table index value. By specifying 
a value to this function, you are redefining the height, width, and color 
previously associated with this pattern bundle table index. 


offset_column_number 
offset_row_number 


data type: integer 
access: read-only 
mechanism: by reference 


These arguments are the offset into the color index array. You can begin 
mapping color index values from the interior of the array, if you desire. 


The offset determines the number of array columns and rows that you 
specify as arguments to SET PATTERN REPRESENTATION. For instance, 
if the offset is the first element of the array, you can specify the full 
dimensions of the color index array as the “number of columns to map” and 
the “number of rows to map.” 


For a detailed discussion of this argument, refer to the CELL ARRAY 
arguments in Chapter 4, Output Functions. 
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num_columns 


num_rows 

data type: integer 
access: read-only 
mechanism: by reference 


These arguments specify the number of rows and columns, beginning at 
the offset element, to map from the color index array to the pattern. For a 
detailed discussion of this argument, refer to the CELL ARRAY argument 
descriptions in Chapter 4, Output Functions. 


color_index_array 


data type: 2D array (integer) 
access: read-only 
mechanism: by descriptor 


This argument is the array containing the color index values for each 
individual cell in the pattern. The array must have at least the dimensions 
that you specified as the height and width arguments. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 

20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 

25 GKS$_ERROR_25 Specified workstation is not open 
in routine **** 

33 GKS$_ERROR_33 Specified workstation is of cate- 


gory MI in routine **** 
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Error 
Number 


35 


36 


85 


90 


91 


93 


Program Example 


Completion 
Status Code 


GKS$_ERROR_35 


GKS$_ERROR_36 


GKS$_ERROR_85 


GKS$_ERROR_90 


GKS$_ERROR_91 


GKS$_ERROR_93 


Message 


Specified workstation is of cate- 
gory INPUT in routine **** 


Specified workstation is 
Workstation Independent Segment 
Storage in routine **** 


Specified pattern index is invalid 
in routine **** 


Interior style PATTERN is not 
supported on this workstation in 
routine **** 


Dimensions of color array are 
invalid in routine **** 


Color index is invalid in routine 
wR 


Example 5-28 illustrates the use of the function SET PATTERN 
REPRESENTATION. Following the program example, Figure 5-27 
illustrates the program’s effect on a VT241 workstation. — 
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Example 5—23: Changing the Pattern Representation 


IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, NUM_POINTS, BLUE, 


* FILL INDEX, PAT_INDEX, NUM_ROWS, NUM_COLS, PAT ARRAY ( 2,2 ), 
* SEG NAME, OFFSET_COL, OFFSET_ROW 
DATA WS_ID / 1 /, NUM_POINTS / 4 /, 
* FILL INDEX / 8 /, PAT_INDEX / 5 /, BLUE / 3 /, 
* NUM_ROWS / 2 /, NUM_COLS / 2 /, 


* PAT ARRAY / 3,2, 2,3 /, 
* SEG NAME / 1 /, OFFSET_COL / 1 /, OFFSET_ROW / 1 / 


DATA PX /.1, .9, .9, .1 / 
DATA PY /.1, .1, .9, .9 / 
REAL PX( 4 ), PY( 4 ) 
INTEGER FLAGS( 13 ) 


CALL GKS$OPEN_GKS( 'SYSS$ERROR:’ ) 
CALL GKS$OPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE WS( WS_ID ) 


FLAGS( 11 ) = GKS$K_ASF_BUNDLED 
FLAGS( 12 ) = GKS$K_ASF_ BUNDLED 
FLAGS( 13 ) = GKS$K_ASF_BUNDLED 
CALL GKS$SET_ASF( FLAGS ) 


Store the output in a segment. 
CALL GKS$CREATE_SEG( SEG_NAME ) 


CALL GKS$SET_FILL_INDEX( FILL_INDEX ) 
CALL GKS$FILL_AREA( NUM POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG() 


Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


CALL GKS$SET_PAT_REP( WS_ID, PAT_INDEX, OFFSET_COL, 
* OFFSET_ROW, NUM_COLS, NUM_ROWS, %DESCR( PAT _ARRAY ) ) 


(continued on next page) 
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Example 5-23 (Cont.): Changing the Pattern Representation 


— C¢ 


Update the screen to reflect the change. 
CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM_FLAG ) 
READ (5, *) 


CALL GKSS$DEACTIVATE_WS( WS_ID ) 
CALL GKSS$CLOSE_WS( WS_ID ) 
CALL GKSS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


The fill area bundle table number 8 contains an entry for the pattern 
index. For the VT241, fill area bundle number 8 specifies an associated 
pattern index value of 5. 


Define the pattern array. The pattern consists of alternating rows of 
blue and red combinations. Other workstations may define other index 
values for the colors blue and red. For more information, refer to the 
DEC GKS Device Specifics Reference Manual. 


PX contains the polygon’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .1). 


This code initializes the elements of the array that affect all the nongeo- 
metric polymarker attributes. This code sets each ASF to GKS$K_ASF_ 
BUNDLED. The parameter (flags)( 11 ) corresponds to the current fill 
area interior style, flags( 12 ) corresponds to the current fill area style 
index, and flags( 13 ) corresponds to the fill area color index. 


See the SET ASPECT SOURCE FLAGS function description in this 
chapter for more information. 


© On a VT241, setting the fill area bundle table index to the value 8 


specifies a dark red pattern for the fill area style. 


© Ona VT241, calling SET PATTERN REPRESENTATION causes an 


implicit regeneration that is suppressed by the workstation (by default). 
The attribute changes are not made and the screen is out of date. You 
need to call UPDATE WORKSTATION to update the surface of the 
workstation. 
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If your workstation requires an implicit regeneration to implement 
changes to pattern representation but does not suppress the regeneration | 
by default, the workstation redraws only the visible segments on the 
workstation surface. Output primitives not contained in segments 
are lost. For a complete discussion of implicit regeneration, refer to 
Chapter 3, Control Functions. 


Figure 5-27 shows the VT241 surface after the program was executed. The 


color of the triangle changed from a red and black pattern to a red and blue 
pattern. 


Figure 5-27: Changing the Pattern Representation—VT241 
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SET POLYLINE REPRESENTATION 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET POLYLINE REPRESENTATION allows you to redefine 


_an existing polyline bundle table index representation, or to define a new 


polyline bundle table index value, by specifying the line type, the line width, 
and the line color index associated with the specified bundle index. 


Depending on the capabilities of your workstation, a call to this function 
may cause DEC GKS to implicitly regenerate the workstation surface. For 
information concerning implicit regeneration, refer to Chapter 3, Control 
Functions. 


Attribute values passed to this function must be valid for the specified 
workstation. For information, refer to the DEC GKS Device Specifics 
Reference Manual. 


GKS$SET_PLINE REP (workstation_id, polyline_index, 
line_type, line_width, color_index) 


GSPLR_ (workstation_id, pindex, Itype, lwidth, cindex) 
gsetlinerep (workstation_id, index, rep) 
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Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in Chapter 3, Control Functions). 


polyline_index 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the polyline bundle table index value. By specifying a 
value to this function, you are redefining the polyline type, width, and color 
previously associated with this polyline bundle table index. . 


line_type 

data type: integer 
access: read-only 
mechanism: by reference 


This argument specifies the type of the polyline. The argument can be any 
of the following values or constants: 


Value Constant Description 

<0 Device-dependent types. 

1 GKS$K_LINETYPE_SOLID Use solid line. | 

2 GKS$K_LINETYPE_DASHED Use dashed line. 

3 GKS$K_LINETYPE_DOTTED Use dotted line. 

4 GKS$K_LINETYPE_DASHED_DOTTED Use dashed-dotted line. 

>= 5 Reserved: future stan- 
dardization. 


See SET LINETYPE in this section for more information. 
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line_width 

data type: real 

access: read-only 
mechanism: by reference 


This argument is the line width scale factor that is multiplied by the 
workstation’s nominal line width to adjust the width of the polyline. See 
SET LINEWIDTH SCALE FACTOR in this section for more information. 


color_index 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the color index of the polyline. See SET POLYLINE 
COLOR INDEX for more information. . 


Error Messages 


Error Completion 

Number Status Code Message 

-20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state: GKS 

shall be in one of the states WSOP, 

WSAC, or SGOP in routine **** 

20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 

25 GKS$_ERROR_25 | Specified workstation is not open 
in routine **** 

33 GKS$_ERROR_33 Specified workstation is of cate- 

gory MI in routine **** 
35 GKS$_ERROR_35 Specified workstation is of cate- 


gory INPUT in routine **** 
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Number 


36 


60 


63 


64 


65 


93 


Program Example 


Completion 
Status Code 


GKS$_ERROR_36 


GKS$_ERROR_60 
GKS$_ERROR_63 
GKS$_ERROR_64 
GKS$_ERROR_65 


GKS$_ERROR_93 
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Message 


Specified workstation is 
Workstation Independent Segment 
Storage in routine **** 


Polyline index is invalid in routine 
KR 


Specified linetype is equal to zero 
in routine **** 


Specified linetype is not supported 
on this workstation in routine **** 


Linewidth scale factor is less than . 
zero in routine **** 


Color index is invalid in routine 
KEK 


Example 5-24 illustrates the use of the function SET POLYLINE 
REPRESENTATION. Following the program example, Figure 5-28 
illustrates the program’s effect on a VT241 workstation. 
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Example 5-24: Changing the Polyline Representation 


This program sets the Attribute Source Flags (ASFs) to bundled, 
shows the polyline corresponding to the bundle value 8, and then 
changes the attributes of bundle number 8, using the function 
GKSSSET_PLINE_REP. 
IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, NUM_POINTS, PLINE_INDEX, GREEN, 

* SEG NAME 

REAL TIMES FIVE 

DATA WS_ID / 1 /, NUM_POINTS / 5 /, 
* PLINE_INDEX / 8 /, GREEN / 1 /, TIMES FIVE / 5.0 /, 
* SEG NAME / 1 / 

REAL PX( 5 ), PY( 5 ) 
1) DATA PX /.2, .95 7, +7, «9/ 
DATA PY /.5, .5, .6, .4, .5/ 

INTEGER FLAGS( 13 ) 


aaanaa 


CALL GKSSOPEN_GKS( 'SYS$ERROR:’ ) 
CALL GKSSOPEN WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE WS( WS_ID ) 


S FLAGS( 1 ) = GKS$K_ASF_ BUNDLED 

. FLAGS( 2 ) = GKS$K_ASF_BUNDLED 
FLAGS( 3 ) = GKS$K_ASF BUNDLED 
CALL GKS$SET_ASF( FLAGS ) 


Cc Store the output in a segment. 
CALL GKS$CREATE_SEG( SEG_NAME ) 


3 ] CALL GKSSSET_PLINE_INDEX( PLINE_INDEX ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG() 


c Release deferred output. Pause. Type RETURN when you are finished 
c viewing the picture. 
CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 
READ (5, *) 
4] CALL GKS$SET_PLINE REP( WS_ID, PLINE_INDEX, 


* GKSSK_LINETYPE SOLID, TIMES FIVE, GREEN ) 


C Update the screen to reflect the changes. 
CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM FLAG ) 


(continued on next page) 
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Example 5—24 (Cont.): Changing the Polyline Representation 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKSSCLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


PX contains the polygon’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .5). 


This code initializes the elements of the array that affect all the nonge- 
ometric polyline attributes. This code sets each ASF to GKS$K_ASF_ 
BUNDLED. The parameter (flags)( 1 ) corresponds to the line type, 
flags( 2 ) corresponds to the line width scale factor, and flags( 3 ) corre- 
sponds to the polyline color index. 


See the SET ASPECT SOURCE FLAGS function description in this 
chapter for more information. 


© Using the VT241, setting the polyline index to the value 8 generates a 


red, dotted polyline of nominal width. 


On a VT241, calling SET POLYLINE REPRESENTATION causes an 
implicit regeneration that is suppressed by the workstation (by default). 
The attribute changes are not made and the screen is out of date. You 
need to call UPDATE WORKSTATION to update the surface of the 
workstation. 


If your workstation requires an implicit regeneration to implement 
changes to polyline representation but does not suppress the regener- 
ation by default, the workstation redraws only the visible segments on 
the workstation surface. Output primitives not contained in segments 
are lost. For a complete discussion of implicit regeneration, refer to 
Chapter 3, Control Functions. 
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Figure 5-28 shows the screen of a VT241 terminal after the program has 
run to completion. 


Figure 5-28: Changing the Polyline Representation—VT241 
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SET POLYMARKER REPRESENTATION 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET POLYMARKER REPRESENTATION allows you to 
redefine an existing polymarker bundle table index representation, or to 
define a new polymarker bundle table index value, by specifying the marker 
type, the marker size, and the marker color index associated with the 
specified bundle index. 


Depending on the capabilities of your workstation, a call to this function 
may cause DEC GKS to implicitly regenerate the workstation surface. For 
information concerning implicit regeneration, refer to Chapter 3, Control 
Functions. 


Attribute values passed to this function must be valid for the specified 
workstation. For information, refer to the DEC GKS Device Specifics 
Reference Manual. 


GKS$SET_PMARK_REP  (workstation_id, polymarker_index, 
marker_type, marker_size, 
color_index) 


GSPMR_(workstation_id, pindex, mtype, sfactor, cindex) 
gsetmarkerrep (workstation_id, index, rep) 
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Arguments 


workstation_id 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in Chapter 3, Control Functions). 


polymarker_index 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the polymarker bundle table index value. By specifying 
a value to this function, you are redefining the polymarker type, size, and 
color previously associated with this polymarker bundle table index. 


marker_type 


data type: integer 
access: read-only 
mechanism: by reference 


This argument specifies the type of the polymarker. The argument can be 
any of the following values or constants: 


Value Constant Description 

<0 Device-dependent types. 

1 GKS$K_MARKERTYPE_DOT Use dots (.). 

2 GKS$K_MARKERTYPE_PLUS Use plus signs (+). 

3 GKS$K_MARKERTYPE_ASTERISK Use asterisks (*). 

4 GKS$K_MARKERTYPE_CIRCLE Use circles (0). 

5 GKS$K_MARKERTYPE_DIAGONAL_CROSS _ Use diagonal crosses (X). 

>= 6 Reserved: future stan- 
dardization. 


See SET MARKER TYPE in this section for more information. 
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marker_size 


data type: real 
access: read-only 
mechanism: by reference 


This argument is the polymarker size scale factor that is multiplied by the 
workstation’s nominal marker size to adjust the size of the polymarker. See 
SET MARKER SIZE SCALE FACTOR in this section for more information. 


color_index 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the color index of the polymarker. See SET 
POLYMARKER COLOR INDEX for more information. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 

20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 

25 GKS$_ERROR_25 Specified workstation is not open 
in routine **** 

33 GKS$_ERROR_33 Specified workstation is of cate- 
gory MI in routine **** 

35 GKS$_ERROR_35 Specified workstation is of cate- 


gory INPUT in routine **** 
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Error Completion 

Number Status Code Message 

36 GKS$_ERROR_36 Specified workstation is 
Workstation Independent Segment 
Storage in routine **** 

66 GKS$_ERROR_66 Polymarker index is invalid in 
routine **** 

69 GKS$_ERROR_69 Marker type is equal to zero in 
routine **** 

70 GKS$_ERROR_70 Specified marker type is not 
supported on this workstation in 

. routine **** 

71 GKS$_ERROR_71 Specified marker size scale factor 

is less than zero in routine **** 


93 GKS$_ERROR_93 Color index is invalid in routine 


RAKE 





Program Example 
Example 5-25 illustrates the use of the function SET POLYMARKER 


REPRESENTATION. Following the program example, Figure 5—29 illus- 
trates the program’s effect on a VT241 workstation. 


7 
{ 
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Example 5-25: Changing the Polymarker Representation 


aqaanaaAN 


This program sets the Attribute Source Flags (ASFs) to bundled, 
shows the polymarker corresponding to the bundle value 8, and then 
changes the attributes of bundle number 8, using the function 
GKSS$SET_PMARK_ REP. 

IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, NUM_POINTS, 

* PMARK INDEX, GREEN, SEG_NAME 

REAL PX( 5 ), PY¥( 5 ), TIMES TEN 

DATA WS_ID / 1 /, NUM_POINTS / 5 /, 

* PMARK INDEX / 8 /, GREEN / 1 /, TIMES TEN / 10.0 /, 

* SEG NAME / 1 / 


DATA PX fe Lp: 295-37 Ty «97 
DATA PY /.5, .5, .6, .4, .5/ 
INTEGER FLAGS( 13 ) 


CALL GKSSOPEN_GKS( ’SYSSERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKSS$K_CONID_ DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE _WS( WS_ID ) 


FLAGS( 4 ) = GKS$K_ASF_BUNDLED 
FLAGS( 5 ) = GKS$K_ASF_BUNDLED 
FLAGS( 6 ) = GKS$K_ASF_ BUNDLED 
CALL GKS$SET_ASF( FLAGS ) 


Store the output in a segment. 
CALL GKS$CREATE_SEG( SEG_NAME ) 


CALL GKS$SET_PMARK_INDEX( PMARK_INDEX ) 


CALL GKSSPOLYMARKER( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG () 


Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


CALL GKS$SET_PMARK_REP( WS_ID, PMARK_INDEX, 
* GKSS$K_MARKERTYPE PLUS, TIMES TEN, GREEN ) 


Update the surface to reflect the changes. 
CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM FLAG ) 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 

CALL GKS$CLOSE_GKS() 

END 
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The following numbers correspond to the numbers in the previous example: 


@ PX contains the markers’ X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the first point (.1, .5). 


@ This code initializes the elements of the array that affect all the non- 
geometric polymarker attributes. This code sets each ASF to GKS$K_ 
ASF_BUNDLED. The parameter flags( 4 ) corresponds to the marker 
type, flags( 5 ) corresponds to the marker size scale factor, and flags( 6 ) 
corresponds to the polymarker color index. 


See the SET ASPECT SOURCE FLAGS function description in this 
chapter for more information. 


© Setting the polymarker index to the value 8 outputs a small, red circle of 
nominal size. 


@ Ona VT241, calling SET POLYMARKER REPRESENTATION causes an 
implicit regeneration that is suppressed by the workstation (by default). 
The attribute changes are not made and the screen is out of date. You 
need to call UPDATE WORKSTATION to update the surface of the 
workstation. 


If your workstation requires an implicit regeneration to implement 
changes to polymarker representation but does not suppress the regen- 
eration by default, the workstation redraws only the visible segments on 
the workstation surface. Output primitives not contained in segments 
are lost. For a complete discussion of a a peecuereeon. refer to 
Chapter 3, Control Functions. ogy bes ah : 


Figure 5—29 shows the screen of a VT241 terminal after the program has 
run to completion. 
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Figure 5-29: Changing the Polymarker Representation—VT241 
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SET TEXT REPRESENTATION 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET TEXT REPRESENTATION allows you to redefine an 
existing text bundle table index representation, or to define a new text 
bundle table index value, by specifying the text font and precision, the 
character expansion factor, the character spacing, and the text color index 


associated with the specified bundle index. 


Depending on the capabilities of your workstation, a call to this function 
may cause DEC GKS to implicitly regenerate the workstation surface. For 
information concerning implicit regeneration, refer to Chapter 3, Control 
Functions. 


Attribute values passed to this function must be valid for the specified 
workstation. For information, refer to the DEC GKS Device Specifics 
Reference Manual. 


GKS$SET_TEXT_REP (workstation_id, text_index, font_value, 
precision_value, expansion_factor, 
character_spacing, color_index) 


GSTXR_ (workstation_id, tindex, font, precision, efactor, spacing, 
cindex) 


gsettextrep (workstation_id, index, rep) 
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Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that identifies an open workstation (refer 
to OPEN WORKSTATION in Chapter 3, Control Functions). 


text_index 

data type: integer 
access: read-only 
mechanism: by reference 


This argument is the text index value. By specifying a value to this” 
function, you are redefining the associated text font, precision, expansion 
factor, spacing, and color previously associated with this text index value. 


font_value 

data type: integer 
access: read-only 
mechanism: by reference 


This argument is the font value. If you are using the character or string 
precisions, refer to the DEC GKS Device Specifics Reference Manual for more 
information concerning hardware fonts. If using the stroke precision, refer 
to Appendix G, DEC GKS Device-Independent Fonts in this manual. 


See SET TEXT FONT AND PRECISION in this section for more information 
concerning the differences between hardware and software fonts. 


precision_value 


data type: integer 
access: read-only 
mechanism: by reference 
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This argument is the precision value. The argument can be any of the 
following values or constants: 


Value Constant Description 

0 GKS$K_TEXT_PRECISION_STRING Lowest precision 

1 GKS$K_TEXT_PRECISION_CHAR Moderate precision 
2 GKS$K_TEXT_PRECISION_STROKE ___ Highest precision 


Depending on the precision you choose, you may have to use either 
hardware or software fonts. See SET TEXT FONT AND PRECISION for 
more information. 


expansion_factor 


data type: real 
access: read-only 
mechanism: by reference 


This argument is the character expansion factor. This value multiplied 
by the width-to-height ratio specified in the original font specification 
determines the new character width. The character height remains the 
same. 


character_spacing 


data type: real 
access: read-only 
mechanism: by reference 


This argument is the spacing factor. This value, multiplied times the text 
height, is the spacing value in world coordinates. If you specify a positive 
number, the spacing increases between letters (for example, the value 0.1 
sets spacing to be one tenth the character height). If you specify a negative 
number, the spacing decreases (characters may overlap). If you specify the 
value 0.0, the bodies of the characters are adjacent, without any separating 
space not defined as part of the character body by the font design. 


See SET CHARACTER SPACING in this section for more information. 
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data type: 


access: 


mechanism: 


integer 
read-only 
by reference 
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This argument is the color index of the text. See SET TEXT COLOR INDEX 
for more information. 


Error Messages 


Error 
Number 


—20 


20 


25 


33 


35 


36 


72 


Completion 
Status Code 
DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_33 
GKS$_ERROR_35 


GKS$_ERROR_36 


GKS$_ERROR_72 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 
Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 

Specified workstation is of cate- 
gory MI in routine **** 

Specified workstation is of cate- 
gory INPUT in routine **** 


Specified workstation is 
Workstation Independent Segment 
Storage in routine **** 


Text index is invalid in routine 
KEKE 


Output Attribute Functions 5-153 


Representation Functions 
SET TEXT REPRESENTATION 


Error Completion 

Number Status Code Message 

75 GKS$_ERROR_75 Text font is equal to zero in rou- 
tine RK 

76 GKS$_ERROR_76 Requested text font is not sup- 


ported for the specified precision 
on this workstation 


17 GKS$_ERROR_77 Character expansion factor is less 


than or equal to zero in routine 
KR 


93. - -~-—-GKS$_ERROR_93 Color index is invalid in routine 
KEE 
Program Example 


Example 5-26 illustrates the use of the function SET TEXT 
REPRESENTATION. Following the program example, Figure 5-30 
illustrates the program’s effect on a VT241 workstation. 
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Example 5-26: Changing the Text Representation 


Cc This program changes the text representation of the index 
C value 5. 
IMPLICIT NONE 
INCLUDE ’SYS$LIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, FIVE, OLD ENGLISH, GREEN, SEG_NAME 
REAL LARGER, START PT _X, START_PT Y, ONE TENTH, TIMES TWO 
DATA WS_ID / 1 /, LARGER / 0.03 /, FIVE / 5 /, 
* START PT X / 0.1 /, START_PT_Y / 0.5 /, 
* OLD ENGLISH / -18 /, ONE_TENTH / 0.1 /, GREEN / 1 /, 
* TIMES TWO / 0.02 /, SEG_NAME / 1 / 
_ INTEGER FLAGS( 13 ) 


CALL GKSS$OPEN_GKS( 'SYS$ERROR:’ ) 
CALL GKS$OPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKSS$ACTIVATE_WS(-WS_ID ) 


CALL GKS$SET_TEXT_HEIGHT( LARGER ) 


FLAGS( 7 ) = GKS$K_ASF_BUNDLED 
FLAGS( 8 ) = GKS$K_ASF_ BUNDLED 
FLAGS( 9 ) = GKSS$K_ASF BUNDLED 
FLAGS( 10 ) = GKS$K_ASF_BUNDLED 


CALL GKS$SET_ASF( FLAGS ) 


Cc Store output in a segment. 
CALL GKSS$CREATE_SEG( SEG_NAME ) 


CALL GKS$SET_TEXT_INDEX( FIVE ) 
CALL GKS$TEXT( START PT X, START PT Y, ‘Imitation Life’ ) 
CALL GKS$CLOSE_SEG() 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKSSUPDATE WS( WS_ID, GKSSK_POSTPONE_FLAG ) 

READ (5, *) 


CALL GKS$SET_TEXT REP( WS ID, FIVE, OLD ENGLISH, 
* GKS$K_TEXT PRECISION STROKE, TIMES TWO, ONE_TENTH, GREEN ) 


Cc Update the surface to reflect the changes. 
CALL GKSS$UPDATE_WS( WS_ID, GKS$K_PERFORM_ FLAG ) 





(continued on next page) 
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Example 5-26 (Cont.): Changing the Text Representation 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ This code increases the character height so that the string is easy to see. 


@ This code initializes the elements of the array that affect all the nongeo- 
metric polymarker attributes. This code sets each ASF to GKS$K_ASF_ 
BUNDLED. The parameter flags( 7 ) corresponds to the text font and 
precision, flags( 8 ) corresponds to the character expansion factor, 
flags( 9 ) corresponds to the character spacing, and flags( 10 ) corre- 
sponds to the text color index. 


See the SET ASPECT SOURCE FLAGS function description in this 
chapter for more information. 


© Setting the text index to the value 5 outputs red text in stroke precision, 
with hardware font 1 at the default width and spacing. 


@ Ona VT241, calling SET TEXT REPRESENTATION causes an implicit 
regeneration that is suppressed by the workstation (by default). The 
attribute changes are not made and the screen is out of date. You 
need to call UPDATE WORKSTATION to update the surface of the 
workstation. 


If your workstation requires an implicit regeneration to implement 
changes to text representation but does not suppress the regeneration 
by default, the workstation redraws only the visible segments on the 
workstation surface. Output primitives not contained in segments 
are lost. For a complete discussion of implicit regeneration, refer to 
Chapter 3, Control Functions. 


Figure 5-30 shows the screen of a VT241 terminal after the program has 
run to completion. 


5~—156 Output Attribute Functions 


Representation Functions 
SET TEXT REPRESENTATION 


Figure 5—30: Changing the Text Representation—VT241 
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Pick Attributes 


Pick Attributes 


Setting pick identifiers allows you another level of naming sections within 
segments so that a user can pick portions of a segment without having to 
pick the whole segment. 
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Pick Attributes 
SET PICK IDENTIFIER 


SET PICK IDENTIFIER 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


This function sets the current pick identifier value in the DEC GKS state 
list to be the number you specify. All subsequent output primitives stored in 
segments are assigned this value until you change it. 


Setting pick identifiers allows you another level of naming sections within 
segments so that a user can pick portions of a segment without having to 
pick the whole segment. 


NOTE 


DEC GKS continues to recognize the last pick identifier specified, 
even after you close a segment. If you open another segment, 
DEC GKS continues to associate the current segment identifier 
with the newly output images. Consequently, if you specify a 
pick identifier in one segment, make sure that you set the pick 
identifier properly when opening another segment. 


Syntax 


SET PICK IDENTIFIER  (pick_id) 
GSPKID  (pick_id) 
gsetpickid (pick_id) 
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SET PICK IDENTIFIER 
Arguments 
pick_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the new pick identifier. 


Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
8 GKS$_ERROR_8 

97 GKS$_ERROR_97 


Program Example 


Message 
GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state; GKS 
shall be in one of the states GKOP, 
WSOP, WSAC, or SGOP 


Pick identifier is invalid 


Example 5—27 illustrates the use of the function SET PICK IDENTIFIER. 
Following the program example, Figure 5-31 illustrates the program’s effect 


on a VT241 workstation. 
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Example 5-27: Setting Pick Identifiers 


Cc This program initializes and requests pick input from a VT241. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, INITIAL STATUS, SEGMENT, 
* PICK_ID, PROMPT ECHO TYPE, ERROR_STATUS, 
* INPUT MODE, ECHO FLAG, RECORD BUFFER_LENGTH, 
* RECORD _SIZE, INPUT_STATUS DEVICE_NUM, INPUT_CHOICE, 
* BOX_1, BOX_2, TRIANGLE_1, TRIANGLE_2, NUM_POINTS 


1] REAL ECHO AREA(4), DATA_RECORD( 1 ) 
REAL X_VALUES( 4 ), Y_VALUES( 4 ) 
DATA WS_ID / 1 /, DEVICE_NUM / 1 /, BOX1/1/, 
* BOX 2 / 2 /, TRIANGLE_1 / 1 /, TRIANGLE 2 / 2 /, 
* NUM_POINTS / 4 / 
DATA X_VALUES / 0.1, 0.4, 0.1, 0.1 / 
DATA Y_VALUES / 0.3, 0.6, 0.6, 0.3 / 


CALL GKS$OPEN_GKS( ’SYS$ERROR:’ ) 
CALL GKS$OPEN WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKSS$ACTIVATE_WS( WS_ID ) 


CALL GKS$SET_FILL_ INT STYLE( GKS$K_INTSTYLE_SOLID ) 


e CALL GKS$CREATE_SEG( BOX_1 ) 

CALL GKS$SET_PICK_ID( TRIANGLE_1 ) 

CALL GKS$SET_FILL COLOR_INDEX( 2 ) 

CALL GKS$FILL_AREA( NUM POINTS, X_VALUES, Y_VALUES ) 
X_VALUES( 3 ) = 0.4 

Y_VALUES( 3 ) = 0.3 

CALL GKS$SET_PICK_ID( TRIANGLE 2 ) 

CALL GKS$SET_FILL_COLOR_INDEX( 3 ) 

CALL GKS$FILL_AREA( NUM_POINTS, X_VALUES, Y_VALUES ) 
CALL GKS$CLOSE_SEG () 


© X_VALUES( 1 ) = 0.6 
X_VALUES( 2 ) = 0.9 
X_VALUES( 3 ) = 0.6 
X_VALUES( 4 ) = 0.6 
Y_VALUES( 3 ) = 0.6 


CALL GKS$SET_PICK_ID( TRIANGLE 1 ) 


(continued on next page) 
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Example 5—27 (Cont.): Setting Pick Identifiers 





4) CALL GKSSCREATE_SEG( BOX 2 ) 

CALL GKS$SET_FILL COLOR_INDEX( 2 ) 

CALL GKS$FILL_AREA( NUM POINTS, X_ VALUES, Y_VALUES ) 
X_VALUES( 3 ) = 0.9 

Y_VALUES( 3 ) = 0.3 

CALL GKS$SET PICK ID( TRIANGLE 2 ) 

CALL GKS$SET FILL COLOR INDEX( 3 ) 

CALL GKS$FILL_AREA( NUM POINTS, X VALUES, Y_VALUES ) 
CALL GKS$CLOSE_SEG () 


CALL GKSSSET_SEG DETECTABILITY ( BOX_1, GKS$K_DETECTABLE ) 
CALL GKS$SET_SEG_ DETECTABILITY ( BOX_2, GKS$K_DETECTABLE ) 


6 CALL GKS$SET_TEXT _HEIGHT( 0.03 ) 
CALL GKSS$TEXT( 0.2, 0.45, ‘1’ ) 
CALL GKSSTEXT( 0.3, 0.45, '2’ ) 
CALL GKSSTEXT( 0.7, 0.45, ‘1’ ) 
CALL GKS$TEXT( 0.8, 0.45, ’2’ ) 


Cc Declare a data length of one long word which will hold the 
Cc size of the pick prompt. 
© RECORD _BUFFER_LENGTH = 4 


CALL GKS$INQ_PICK_STATE( WS_ID, DEVICE_NUM, 
GKS$K_VALUE_REALIZED, ERROR_STATUS, INPUT _MODE, 

ECHO FLAG, INITIAL STATUS, SEGMENT, PICK_ID, PROMPT _ECHO TYPE, 
ECHO_AREA, DATA_RECORD, RECORD _BUFFER_LENGTH, 

RECORD_SIZE ) . 


* + & 


@ SEGMENT = BOX_1 
PICK_ID = TRIANGLE 1 
PROMPT_ECHO TYPE = 1 
INITIAL STATUS = GKS$K_STATUS_NOPICK 


8] CALL GKSSINIT_PICK( WS_ID, DEVICE_NUM, INITIAL STATUS, 
* SEGMENT, PICK_ID, PROMPT_ECHO TYPE, ECHO AREA, 
* DATA_RECORD, RECORD BUFFER LENGTH ) 


© CALL GKS$SET_PICK_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE REQUEST, GKS$K_ECHO ) 


(continued on next page) 
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Example 5-27 (Cont.): Setting Pick Identifiers 


© 


CALL GKSSREQUEST_PICK( WS_ID, DEVICE_NUM, INPUT_STATUS, 
* SEGMENT, PICK_ID ) 


Output the input choice number. 
WRITE (6,*) INPUT_STATUS, SEGMENT, PICK_ID 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


The data record is one real value that represents the size of the pick 
prompt (or aperture) in device coordinates. 


The echo area variable is an array of real numbers representing the 
rectangular echo area, in device coordinates. The echo area defines a 
portion of the workstation surface on which the prompt moves. 


This code creates a box on the left side of the workstation surface and 
places it in a segment. The code divides the box diagonally and sets pick 
identifiers for each of the created fill area triangles. 


@® This code resets the X and Y world coordinate values so that the coordi- 


nate values specify a new position for the next box. 


This code creates a box on the right side of the workstation surface and 
places it in a segment. The code divides the box diagonally and sets pick 
identifiers for each of the created triangles. 


This code labels the triangles by their pick identifiers. 


This code initializes the size of the data record. This variable is a 
modifiable variable passed to INQUIRE PICK DEVICE STATE, and you 
must initialize it before calling the inquiry function. 

The function INQUIRE PICK DEVICE STATE initializes the vari- 

ables needed by the input functions. The argument GKS$K_VALUE_ 
REALIZED tells the graphics handler to pass the input values as they 
are implemented by the graphics handler, as opposed to the way that the 
application may have set the values (GKS$K_VALUE_SET). 
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The second to last argument specifies the length of the argument that is 
to contain the data record. After DEC GKS returns the data record, it 
modifies this argument to contain the length of the returned data record. 
By comparing the last two arguments, you can tell whether your data 
record variable was large enough to hold the entire data record. 

@ This code assigns new values to the input variables. For instance, the 
initial segment identifier has the value 1. 


© The function INITIALIZE PICK initializes the request for choice input. 
© 


You must pass GKS$K_INPUT_MODE_REQUEST as an argument to 
the function SET PICK MODE, since the DEC GKS software does not 
support sample or event mode. You can use this function to enable (as in 
this example) or to disable input prompt echoing. 


@ The function REQUEST PICK prompts the user for input. The segment 
and pick identifiers are written to the last arguments. 


Figure 5-31 shows the screen of a VT241 terminal at the request for input. 
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Figure 5-31: Setting Pick Identifiers—VT241 





ZK-5087-86 


Output Attribute Functions 5-165 


Chapter 6 


Transformation Functions 


The DEC GKS transformation functions allow you to compose a picture, to 
control how much of the picture is seen on the workstation surface, and to 
control how much of the workstation surface is used to display the picture. 
The following list presents the transformation functions by category: 


Category GKS Functions 


Normalization SELECT NORMALIZATION TRANSFORMATION 
SET CLIPPING 
SET VIEWPORT 
SET VIEWPORT INPUT PRIORITY 
SET WINDOW 
Workstation SET WORKSTATION VIEWPORT 
SET WORKSTATION WINDOW 


When you request input and generate output by means of the workstation 
surface, you are actually working with a number of coordinate systems. The 
image is transformed from one coordinate system to the next. 


Using DEC GKS, you are working with three coordinate systems, as follows: 
¢ World coordinate system 

¢ Normalized device coordinate (NDC) system 

¢ Device coordinate system 

The world coordinate system is an imaginary coordinate plane used to plot 
a graphical image. The NDC system is a device-independent, imaginary 
coordinate plane on which you compose a picture using designated portions 
of the world coordinate plane. Once you compose a picture on the NDC 


space, you can zoom in on the picture, pan across the picture, or zoom out of 
the picture, while controlling what portion of the device coordinate system 
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is used to display the picture. You can display all or part of the picture in 
NDC space on the surface of the physical device. 


When you call one of the DEC GKS output functions, you specify world 
coordinate points. Using a series of default windows and viewports, the 
output primitive is transformed from an image on the world coordinate 
plane, to an image on the NDC plane, and finally, to the surface of the 

workstation. . 


If you do not change the default transformation settings, image shape and 
position are consistent, and your ability to compose complex pictures may be 
limited to what you can form on one area of the world coordinate system. 
The DEC GKS transformation functions allow you to set the windows, 
viewports, and other transformation features that control the transformation 
process, and usually, how generated output appears on the workstation 
surface. 


6.1 World Coordinates and Normalization Transformations 


The world coordinate system is an imaginary, Cartesian coordinate system 
whose X and Y axes extend infinitely in all four directions. The origin of 
the system is the point (0.0, 0.0). Depending on the type of data needed to 
plot your images, you can use any portion of the world coordinate plane. 
For instance, if the necessary data contains negative numbers, you can use 
the portions of the world coordinate system that extend into the negative 
portions of the axes. 


By default, DEC GKS transforms images according to a square world 
coordinate range whose lower left corner is the point (0.0, 0.0) and whose 
sides extend from the point 0.0 to 1.0 on both the X and Y axes. (From 
this point forward, this manual documents rectangular regions such as the 
default range as follows: ({0,1] x [0,1]), zero to one on both the X and Y 
axes.) This range is called the default normalization window. 


DEC GKS transforms the plotted images, according to the current window, 
to an area on the NDC plane. You can reset the window many times while 
generating output primitives, or you can use only the default window, 
depending on the needs of your application. If your image is composed 

of points that lie outside of the world window, then those points may or 
may not be part of the image on the NDC plane depending on the current 
clipping indicator. Clipping is discussed in detail in Section 6.1.1. 


6—2 Transformation Functions 


As an example, consider the formation of a picture of a house on the world 
coordinate plane. To illustrate the resetting of the normalization window, 
consider a coordinate range of ([0,10] x [0,10]). The following code example 
shows how to set such a range for the normalization window. 


DATA PX / 4.0, 1.0, 1.0, 4.0, 2.5, 1.0, 4.0, 4.0, 1. 
DATA; PY -/-4.0,. 1.09% 7.0, -750,: 9.0, 750% 120; 720) 1 8 
CALL GKSS$SET_WINDOW( 1, 0.0, 10.0, 0.0, 10.0 ) 

CALL GKS$SELECT_XFORM( 1 ) 

CALL GKSS$POLYLINE( 9, PX, PY ) 


0 / 
0 / 


PX contains the house’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the lower right corner of the house (4.0, 1.0). 


In the call to SET WINDOW, the window’s X axis minimum value is set to 
the point 0.0 and its maximum value is set to 10.0. The window’s Y axis 
minimum and maximum values are set to the same world coordinates. 
These dimensions establish the rectangle used as the normalization window. 


The first argument to SET WINDOW (the number 1) specifies a 
normalization transformation number. A normalization transformation is a 
transposition of an image from the world coordinate plane to the NDC plane. 
When you select normalization transformation number 1 by calling SELECT 
NORMALIZATION TRANSFORMATION, DEC GKS establishes a window 
of the range ([0,10] x [0,10]) to be the current normalization window. When 
you generate output using this code example, DEC GKS maps the current 
window to a default portion of the NDC space. Section 6.1.1 describes the 
NDC plane in detail. 


Figure 6-1 illustrates the formation of the house on the world coordinate 
plane. 
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Figure 6-1: The World Coordinate Plane 
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6.1.1 The Normalized Device Coordinate (NDC) System 


As mentioned in the previous section, the normalization transformation is 
the transposition of world coordinate points to NDC points. The NDC plane 
is a device-independent coordinate plane on which you compose graphical 
pictures. The NDC plane has an X and Y axis that in theory extends 
infinitely in all four directions with an origin at point (0.0, 0.0), but in 
practice, only images contained in the range ([0,1] x [0,1]) can ultimately be 
transformed to the surface of a physical device. 


When DEC GKS transforms an image from the normalization window to the 
NDC plane, there must be a corresponding rectangle on which to map the 
contents of the window. This rectangular portion of the NDC space is called 
the normalization viewport. The default viewport has the range 

({0,1] x [0,1]) in NDC point values. The previous code example, by default, 
maps the contents of the current window to this default viewport. 


By default, DEC GKS maps the normalization window ([0,1] x [0,1]) in 
world coordinates to the viewport ([0,1] x [0,1]) in NDC point values. 

This transformation is called the unity transformation, which has the 
normalization transformation number 0. You cannot reset the window and 
viewport associated with the unity transformation. All the examples in 
Chapter 4, Output Functions, use the unity transformation. 


You can think of the normalization process as a way of possibly transposing 
a number of areas of the world coordinate plane onto the NDC plane in 
respect to current normalization window and viewport. For instance, DEC 
GKS maps the contents of the current normalization window onto the 
current viewport. If clipping is enabled (which is the default situation), the 
effect is like cutting the window from the world coordinate plane, mapping, 
and then pasting the window to the viewport on the NDC plane. DEC 
GKS maps only images or portions of images plotted within the boundaries 
of the normalization window to the area within the viewport on NDC 
space. If clipping is disabled, DEC GKS maps points that lie outside of the 
normalization window boundary to NDC space outside of the normalization 
viewport but within the range ([0,1] x [0,1)). 


Since DEC GKS clips images at the boundary of the normalization viewport, 
this viewport is also called the clipping rectangle. You can enable and dis- 
able clipping by calling the function SET CLIPPING. Figure 6—2 illustrates 
the clipping process according to the argument passed to SET CLIPPING. 
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Figure 6-2: The Clipping Rectangle 
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As one option to consider while creating a picture, you can select different 
normalization transformations with different windows and viewports, thus 
mapping various portions of the world coordinate space onto different por- 
tions of the NDC space. (In DEC GKS, valid normalization transformation 
numbers range from 0 to 255, and can associate windows and viewports with 
all but the unity transformation number 0.) 


6—6 Transformation Functions 


You can achieve the same effect by reassigning different windows and 
viewports to a single normalization number. 


In essence, you use the world coordinate space as a scratch pad and the 
NDC space as a pasteboard on which to compose an entire picture. For 
instance, if you want an output primitive to appear on the right side of 

a picture appearing on the workstation surface, you map the primitive to 
the right side of the NDC space during the normalization transformation. 
All picture composition is done using normalization transformations. Once 
you compose a picture on the NDC plane, you can output all or part of the 
picture to all or part of various workstation surfaces. 


The following code examples show how to compose a picture using different 
normalization windows and viewports. 


DATA PX / 4.0, 1.0, 1.0, 4.0, 2.5, 1.0, 4.0, 4.0, 1.0 / 
DATA PY / 1.0, 1.0, 7.0, 7.0, 9.0, 7.0, 1.0, 7.0 0 / 


, 


CALL GKSSSET_WINDOW( 1, 0.0, 10.0, 0.0, 10.0 ) 
CALL GKSSSET_VIEWPORT( 1, 0.5, 1.0, 0.5, 1.0 ) 
CALL GKSSSELECT_XFORM( 1 ) 


CALL GKSSPOLYLINE( 9, PX, PY ) 


Normalization transformation number 1 transforms the window in 
Figure 6-1 to a portion of the NDC space as shown in Figure 6-3. 
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Figure 6-3: The Normalization Viewport 
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6—8 Transformation Functions 


By selecting a different normalization transformation with a different 
viewport, you can transpose the same window onto another portion of the 
NDC space. To see how this is accomplished, review the following code 


example: 


DATA 
DATA 


CALL 
CALL 


CALL 
CALL 


Cc Make 
CALL 
CALL 


Cc Make 
CALL 
CALL 


PX / 4.0, 1.0, 1.0, 4.0, 2.5, 1.0, 4.0, 4.0, 
PY / 1.0, 1.07 7:0, 7:0; 9.0; 7.0, 1.0,. 7.0, 


GKSS$SET_WINDOW( 1, 0.0, 10.0, 0.0, 10.0 ) 
GKS$SET_VIEWPORT( 1, 0.5, 1.0, 0.5, 1.0 ) 


GKS$SET_WINDOW( 2, 0.0, 10.0, 0.0, 10.0 ) 
GKS$SET_VIEWPORT( 2, 0.0, 0.5, 0.0, 0.5 ) 


normalization transformation #1 the current transformation. 
GKSS$SELECT_XFORM ( 1) 
GKSSPOLYLINE( 9, PX, PY ) 


normalization transformation #2 the current transformation. 
GKS$SELECT_XFORM( 2 ) 
GKSSPOLYLINE( 9, PX, PY ) 


After execution of this code example, the NDC space contains the images 

in Figure 6-4. In this manner, you can map a number of normalization 
windows to a number of viewports until you compose a complete picture on 
the NDC space. See Section 6.2 to learn how to display the composed picture 
on the workstation surface. 
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Figure 6-4: Composing a Picture on the NDC Plane 
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6.1.2 Overlapping Viewports 
When you define normalization viewports, it is possible to cause them to 


overlap on the NDC plane. You must consider the effects this has during 
input requests. Viewport input priority does not affect output; the order of 
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the output function calls determines which primitive overwrites the other. 
If you are working with segments, the segment priorities affect overlapping 
segments. For more information, refer to Chapter 8, Segment Functions. 


To illustrate the need for a viewport priority list for use during input, 
consider two viewports: the viewport of the unity transformation number 

0 ([0,1] x [0,1]), and a viewport, belonging to normalization transformation 
number 1, having the range ([0.5,1] x [0.5,1]) in NDC points. Notice that the 
viewport of normalization transformation number 1 overlaps the right side 
of the unity viewport. 


During stroke and locator input, the user positions the cursor on the device 
surface and returns one point (locator) or a series of points (stroke) in device 
coordinates. DEC GKS translates the device coordinates to NDC points 
(Section 6.2 discusses this process in detail). 


Once the device coordinates are transformed to NDC points, DEC GKS must 
transform the NDC points to world coordinate points. To transform the 
point, DEC GKS transforms the point from its viewport (NDC) value to the 
corresponding window (world coordinate) value. However, if the user chooses 
a point on the right half of the default viewport, DEC GKS must decide 
whether to use the unity viewport or the overlapping viewport of transfor- 
mation number 1 to transform the point to world coordinates. DEC GKS 
needs to know to which normalization window the point is to be mapped, 
either the window that corresponds to normalization transformation number 
0, or 1. 


To decide which viewport has a higher input priority, DEC GKS maintains a 
priority list. By default, DEC GKS assigns the highest priority to the unity 
transformation (0). So, in the previous example concerning overlapping 
viewports, DEC GKS would use the unity viewport to transform the NDC 
point. The viewports of all remaining transformations decrease in priority 
as their transformation numbers increase (viewport 0 higher than viewport 
1, 1 higher than 2, 2 higher than 3, and so forth). 


If you want to change the order of the viewport input priority list, you 
must call the function SET VIEWPORT INPUT PRIORITY. You specify a 
normalization transformation number whose priority is to be changed (for 
example, 1), a normalization transformation number as a reference (for 
example, 0), and a flag that specifies that the first transformation is to have 
a lower or higher priority than the reference transformation (for example, 
higher). 
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So, if you called SET VIEWPORT INPUT PRIORITY to give transformation 
number 1 a higher transformation (1 higher than 0, 0 higher than 2, 

2 higher than 3, and so forth), then DEC GKS would use the viewport 
corresponding to transformation number 1 in all cases when viewports 1 and 
0 overlap during locator and stroke input. 


For more information concerning locator and stroke input, refer to 
Chapter 7, Input Functions. 


6.2 Workstation Transformations 


DEC GKS must map the picture on the NDC plane to the surface of one 
or more workstations. To do this, DEC GKS uses a second window and 

a viewport called the workstation window and the workstation viewport. 
The workstation window is a rectangular portion of the NDC plane that 
is mapped onto the rectangular portion of the workstation surface called 
the workstation viewport. Whereas there can be numerous normalization 
transformations, there is only one current workstation window and one 
current workstation viewport. 


DEC GKS uses a default workstation window of the range ([0,1] x [0,1]) in 
NDC points, and uses a default workstation viewport, starting at the lower 
left corner, that is the largest rectangle on the device surface that maintains 
the shape of the picture in the workstation window (Section 6.3 discusses in 
detail the shape of the picture in the workstation window). If you choose, 
you can change the workstation window, but the new boundaries can be no 
larger than the default workstation window boundaries ([0,1] x [0,1]). DEC 
GKS clips all points that exceed the default workstation window boundaries 
before DEC GKS transforms the picture to device coordinates, regardless of 
the current clipping flag setting. 


Whereas the normalization transformation composes the picture on NDC 
space, the workstation transformation presents all or part of the picture on 
all or part of the device surface. For instance, by setting the workstation 
window, you can create the illusion of “panning” across a picture, showing 
successive portions of it at a time, or “zooming in,” showing smaller portions 
of a picture at a time. The DEC GKS User Manual discusses this process in 
detail. 


Your application may require that you change the portion of the workstation 
surface used to display the picture. However, if your program runs on 
several devices, you may not know the proportions of the device coordinate 
system with which you are working. The proportions of the device coordinate 
system are completely device dependent; each device can have a completely 
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dissimilar device coordinate plane with dissimilar maximum X and Y 
coordinate values. 


To determine the maximum boundary of the workstation viewport, you 
should use the function, INQUIRE DISPLAY SPACE SIZE, which returns 
the maximum X and Y values of the workstation display surface. (For 
more information, refer to Chapter 11, Inquiry Functions, or to SET 
WORKSTATION VIEWPORT in this chapter.) 


When you set the workstation window (by calling SET WORKSTATION 
WINDOW) or the workstation viewport (by calling SET WORKSTATION 
VIEWPORT), the new window or viewport may not come into effect 
immediately, depending on the capabilities of your device. Depending on 
your device, the new workstation window or workstation viewport may 
become current immediately, or the workstation surface may need to be 
implicitly regenerated before the new window or viewport becomes current. 
If the workstation needs to regenerate its surface to make a workstation 
transformation current, the screen is cleared and only the primitives stored 
in segments are redrawn. You lose all primitives not contained in segments. 


For a detailed discussion of implicit regeneration and surface update, refer 
to Chapter 3, Control Functions. 


The following code example shows how to change the workstation window 
and viewport on a device that suppresses implicit regenerations: 


CALL GKSS$SET_WINDOW( 1, 0.0, 10.0, 0.0, 10.0 ) 
CALL GKS$SET_VIEWPORT( 1, 0.5, 1.0, 0.5, 1.0 ) 
CALL GKSSSET_WINDOW( 2, 0.0, 10.0, 0.0, 10.0 ) 
CALL GKSS$SET_VIEWPORT( 2, 0.0, 0.5, 0.0, 0.5 ) 


Cc Find the maximum X and Y device coordinate values of your 
Cc device’s type. 
CALL GKS$INQ_MAX DS_SIZE( GKS$K_VT240, ARG2, ARG3, MAX _X, 
* MAX _Y, ARG6, ARG7 ) 


Cc Set a new workstation window in NDC points. 
CALL GKSSSET_WS WINDOW( 1, 0.0, 1.0, 0.25, 1.0 ) 
CALL GKSS$SET_WS VIEWPORT( 1, 0.0, MAX_X, 0.0, MAX Y ) 


Cc Update the screen. Primitives not stored in segments are lost. 
CALL GKSS$UPDATE_WS( 1, GKSS$K_PERFORM_FLAG ) 


Cc Make normalization transformation #1 the current transformation. 
CALL GKSSSELECT_XFORM( 1 ) 
CALL GKSSPOLYLINE( 9, PX, PY ) 


Cc Make normalization transformation #2 the current transformation. 
CALL GKSS$SELECT_XFORM ( 2) 
CALL GKSSPOLYLINE( 9, PX, PY ) 
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After execution of this code example, the NDC space contains the images 

in Figure 6-5. Depending on your device, the surface of your workstation 
would look like Figure 6-6. In most instances, the workstation does not use 
the entire workstation viewport to display the picture. DEC GKS uses the 
portion of device coordinate space, starting at the lower left point, that is the 
largest rectangle within the current workstation viewport that maintains the 
shape of the picture contained in the workstation window. In order to map 
the entire workstation window to the entire viewport, you need to make sure 
that the window and viewport have the same proportions. See Section 6.3 
for more information concerning window and viewport proportions. The 
DEC GKS User Manual contains examples working with the proportions of 
workstation windows and viewports. 


The entire process of an image generation, from normalization transforma- 
tion to workstation transformation, is illustrated in Figure 6-7. 
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Figure 6-5: The Workstation Window 
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Figure 6-6: The Picture on a Generic Device Surface 


DEVICE COORDINATE PLANE 





6-16 Transformation Functions 


Figure 6-7: The Entire DEC GKS Transformation Process 
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6.3 Relative Positioning and Shape 


There is one final consideration when redefining the normalization and 
workstation window and viewport values, and that is the shape of the 
object to be drawn. By default, the image is mapped from a square world 
coordinate plane, to a square portion of the NDC plane, and finally to a 
square portion of the display surface plane. Logically, if you draw a tall, 
thin house in world coordinate values using the default transformations, 
you would see a tall, thin house on the workstation surface. However, if 
you define a tall, thin rectangular normalization window that contains your 
house and then map that window onto the default, square normalization 
viewport, the tall, thin house would appear shorter and wider due to 
mapping from window to viewport. 


Consequently, you should be aware of the difference between the relative 
position of the image and the aspect ratio of the image. In the case of the 
tall, thin house, all the points retain their relative position when mapped 
from the normalization window to the viewport. If the X value of the tip of 
the house is located two-thirds of the way along the X axis in the window, 
it is also located two-thirds of the way along the X axis in the viewport. 
Relatively speaking, if the house is located in the center of the window, it 
will be located in the center of the viewport. 


If you want to retain the shape, or aspect ratio, of the image, you must 
map images from a window to a viewport that has the same proportion, or 
height-to-width ratio. For example, if the X axis is two-thirds as large as 
the Y axis in the normalization window, you must map to a viewport whose 
X axis is two-thirds as large as the Y axis in order to retain the aspect ratio 
of your image. 


Figure 6-8 shows the difference between relative position and aspect ratio. 
Like the window and viewport on the left, all normalization transformations 
retain the relative position. The window and viewport on the right retain 
the aspect ratio of the tall, thin house as well as its relative position. 
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Figure 6-8: Relative Position and Aspect Ratio 
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In contrast to the normalization transformations, DEC GKS automatically 
retains the aspect ratio of the workstation window when mapping to the 
workstation viewport. The mapping from workstation window to worksta- 
tion viewport is not necessarily one-to-one; DEC GKS might not use the 
entire defined workstation viewport. By default, DEC GKS uses the largest 
rectangle, starting at the lower left corner, within the workstation viewport 
that retains the shape of the picture contained in the workstation window. 


For more information concerning normalization transformations, worksta- 
tion transformations, relative positioning, and aspect ratio, refer to the 
DEC GKS User Manual. For more information concerning segments and 
transformations, refer to Chapter 8, Segment Functions. 


6.4 Transformation Inquiries 


The following list presents the inquiry functions that you can use to obtain 
transformation information when writing device-independent code: 


INQUIRE CLIPPING 

INQUIRE CURRENT NORMALIZATION TRANSFORMATION 
NUMBER 

INQUIRE DISPLAY SPACE SIZE 

INQUIRE LIST OF TRANSFORMATION NUMBERS 
INQUIRE MAXIMUM NORMALIZATION TRANSFORMATION 
INQUIRE NORMALIZATION TRANSFORMATIONS 

INQUIRE WORKSTATION TRANSFORMATION 


For more information concerning device-independent programming, refer to 
the DEC GKS User Manual. 


6.5 Function Descriptions 


This section describes the DEC GKS transformation functions in detail. 
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SELECT NORMALIZATION TRANSFORMATION 


SELECT NORMALIZATION TRANSFORMATION 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SELECT NORMALIZATION TRANSFORMATION sets the 
normalization transformation number in the DEC GKS state list as the 
current transformation, and uses the associated window and viewport to 
transform points from the world coordinate system to the NDC system for 
subsequent output generation. 


By default, DEC GKS uses the unity normalization transformation number 
0. Use this when you want to map the default normalization window to the 
default NDC viewport. 


Syntax 
GKS$SELECT_XFORM (iransformation_number) 
GSELNT  (xform) 
gselntran (transform) 

Arguments 


transformation_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the normalization transformation number. To set or reset 
windows and viewports associated with a transformation number, you pass 
this number to SET WINDOW and SET VIEWPORT. After selecting this 
number, any subsequent calls to output functions use the window and 
viewport associated with this number. 
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SELECT NORMALIZATION TRANSFORMATION 


Error Messages 


Error Completion 

Number Status Code 

~20 DECGKS$_ERROR_NEG_20 
8 GKS$_ERROR_8 

50 GKS$_ERROR_50 


Program Example 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be in one of the states GKOP, 
WSOP, WSAC, or SGOP in routine 


eK 


Transformation number is invalid 
in routine **** 


Example 6-1 illustrates the use of the function SELECT NORMALIZATION 
TRANSFORMATION. Following the program example, Figure 6-9 illus- 
trates the program’s effect on a VT241 workstation. 
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SELECT NORMALIZATION TRANSFORMATION 


Example 6-1: Selecting a Normalization Transformation 


aaa 


This program changes the world viewport four times placing 
the "tall, thin house" in each corner of the NDC space. 
IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, UP_LEFT CORNER, UP_RIGHT CORNER, 

* LOW_LEFT CORNER, LOW_RIGHT CORNER, NUM_POINTS 

REAL PX ( 9 ), PY (9), PX_2 (5), PY_2 (5) 


DATA PX / .4, .1, .1, .4, .25,..1, .4, .4, .1/ 
DATA BY¥ -/ w3y) cl eT coe eon - 2 Te ody ole a7 
DATA PX_2 / 0.0, 1.0, 1.0, 0.0, 0.0 / 

DATA PY 2 / 0.0, 0.0, 1.0, 1.0, 0.0 / 
DATA UP_LEFT CORNER / 1 /, UP_RIGHT_CORNER / 2 /, 

* LOW LEFT CORNER / 3 /, LOW! RIGHT | CORNER / 4 /, 

* NUM_! POINTS / 9 /, Ws_ID / 17 


CALL GKS$OPEN_GKS( ‘SYSS$ERROR:’ ) 
CALL GKS$OPEN WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE_WS( WS_ID ) 


CALL GKS$SET_VIEWPORT( UP_LEFT CORNER, 0.0, 0.5, 0.5, 1.0) 

CALL GKS$SET | VIEWPORT ( UP_| RIGHT CORNER, 0.5, 1.0, 0.5, 1.0) 
CALL GKS$SET | |_ VIEWPORT ( LOW _| LEFT CORNER, 0.0, 0.5, 0.0, 0.5) 
CALL GKS$SET_VIEWPORT ( LOW_RIGHT_ CORNER, 0.5, 1.0, 0.0, 0.5) 


Outlining the default world window will result in the outlining of 
the NDC plane, the workstation window, and the workstation 
viewport, by default. 

CALL GKS$POLYLINE( 5, PX_2, PY_2 ) 


CALL GKS$SELECT_XFORM( UP_LEFT_ CORNER ) 

CALL GKSSPOLYLINE( NUM_POINTS, PX, PY ) 

Release deferred output. Pause. Type RETURN when you are finished 
viewing the screen. 

CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 

CALL GKS$SELECT_XFORM( UP_RIGHT CORNER ) 

CALL GKSSPOLYLINE( NUM_POINTS, PX, PY ) 

Release deferred output. Pause. Type RETURN when you are finished 
viewing the screen. 

CALL GKS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 





(continued on next page) 
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SELECT NORMALIZATION TRANSFORMATION 


Example 6-1 (Cont.): Selecting a Normalization Transformation 


CALL GKS$SELECT_XFORM( LOW _LEFT_ CORNER ) 
CALL GKS$POLYLINE( NUM _POINTS, PX, PY ) 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the screen. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE FLAG ) 

READ (5, *) 


CALL GKS$SELECT_XFORM( LOW_RIGHT_CORNER ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 


CALL GKS$DEACTIVATE WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ PX contains the house’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the lower right corner of the house (0.4, 0.1). 


@ This code sets the viewport to be the upper left corner of the NDC 
space and assigns this normalization transformation the value 1. The 
subsequent lines of code set the viewport to be the other three corners of 
the NDC space and assign the normalization transformations the values 
2, 3, and 4. 


© This code selects the normalization transformation number 1, which 
corresponds to a default window and to a viewport that is the upper 
left corner of the NDC space. Until another transformation number is 
selected, output is mapped to the upper left corner of the default NDC 
plane. In this example, the tall, thin house is output to the upper left 
corner of the workstation surface. The next four sections of code change 
the world viewports to the other three corners of the NDC space and 
then generate the tall, thin house in the remaining corners of the default 
NDC space. 


When DEC GKS maps the default workstation window to the worksta- 
tion surface, DEC GKS maps the window to the largest square area on 
the workstation surface (since the workstation window is square) so as 
to maintain the shape of the picture. 
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SELECT NORMALIZATION TRANSFORMATION 


Figure 6—9 shows the screen of a VT241 terminal after the program has run 
to completion. 


Figure 6-9: Selecting the Normalization Transformation—VT241 
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SET CLIPPING INDICATOR 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


The function SET CLIPPING enables or disables clipping of the image at 
the normalization viewport boundary by setting the clipping flag in the DEC 
GKS state list. 


If clipping is enabled, DEC GKS clips all generated output primitives at the 
normalization viewport boundary. If clipping is disabled, primitives may 
exceed the normalization viewport boundaries. By default, DEC GKS clips 
primitives. 


NOTE 


This function works only for the normalization viewport. Pictures 
are always clipped at the workstation window despite the current 
status of the clipping flag. 


Syntax 


GKS$SET_CLIPPING (clip) 
GSCLIP (flag) 
gsetclip (indicator) 
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SET CLIPPING INDICATOR 


Arguments 
clip 
data type: integer 
access: read-only 
mechanism: by reference 


This argument determines whether or not clipping is enabled or disabled. 
The argument can be either of the following values or constants. 


Value Constant Description 
0 GKS$K_NOCLIP Clipping is off. 
1 GKS$K_CLIP _ Clipping is on. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

—23 DECGKS$_ERROR_NEG_23 Invalid value specified for clipping 
flag in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 


shall be in one of the states GKOP, 
WSOP, WSAC, or SGOP in routine 


Rok 


Program Example 
Example 6-2 illustrates the use of the function SET CLIPPING. Following 


the program example, Figure 6-10 illustrates the program’s effect on a 
VT241 workstation. 
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SET CLIPPING INDICATOR 


Example 6-2: Controlling Clipping at the World Viewport 





aaa 


aaa 


aaa 


This program generates a "tall, thin house" that overlaps 
the normalization window and viewport. You can see 

the overlapping portion if clipping is disabled. 

IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS ID, HALF, LOW_LEFT CORNER, NUM_POINTS 

REAL PX (9 ), PY (9), PX_2 (5), PY¥_2 (5) 


DATA: PX. / 4) oly oly ade 6 25y a4 ¢ 64y- 64e al. / 
DATA OYJ ol Sg 21 OU Oe, 1b ep eA 
DATA PX_2 / 0.0, 0.5, 0.5, 0.0, 0.0 / 

DATA PY..2 ./ 0.0; 0.0,.°025,. 0.57 0.07 

DATA NUM_POINTS / 9 /, HALF / 1 /, 

* LOW_LEFT_CORNER / 1 /, WS_ID / 1 / 


CALL GKSSOPEN_GKS( 'SYS$ERROR:’ ) . 
CALL GKS$OPEN _WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


Outlining the default world window will result in the outlining of 
the NDC plane, the workstation window, and the workstation 
viewport, by default. 

CALL GKSSPOLYLINE( 5, PX_2, PY_2 ) 


This window (half of the default window) and viewport (lower 
left corner of the default viewport) are associated with 
normalization transformation number 1. 

CALL GKS$SET_WINDOW( HALF, 0.0, 0.9, 0.0, 0.5) 

CALL GKS$SET_VIEWPORT( LOW_LEFT CORNER, 0.0, 0.5, 0.0, 0.5) 


CALL GKS$SELECT_XFORM( LOW_LEFT CORNER ) 

CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 

Release deferred output. Pause. Type RETURN when you are finished 
viewing the screen. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 





(continued on next page) 
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Example 6-2 (Cont.): Controlling Clipping at the World Viewport 


aaa 


CALL GKS$SET_CLIPPING( GKS$K_NOCLIP ) 


Draw the same house, using the same windows and viewports, but 
with clipping disabled. Now you can see the portion of the house 
that overlaps the window and viewport. 

CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 

CALL GKS$DEACTIVATE WS( WS_ID ) 

CALL GKS$CLOSE_WS( WS_ID ) 

CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


PX contains the house’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the lower right corner of the house (0.4, 0.1). 


This code sets the normalization window to be half of the default plane 
and assigns the normalization transformation low_left_corner 

(number 1). The tall, thin house is cut in half by the window boundary. 
The code also sets the viewport to be the lower left corner of the NDC 
space and assigns this normalization transformation the value 1. 


This code selects normalization transformation number 1 which has a 
smaller window by half and a viewport that is the lower left corner of 
the NDC space. By default, clipping is enabled; you only see half the 
house. 


Once you disable clipping and redraw the picture, DEC GKS maps 
the entire house to the NDC space and eventually to the workstation 
surface. 


Figure 6—10 shows the screen of a VT241 terminal after the program has 
run to completion. 
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SET CLIPPING INDICATOR 


Figure 6-10: Enabling and Disabling Clipping—VT241 
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SET VIEWPORT 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET VIEWPORT associates viewport boundaries on the NDC 
plane with a specified normalization transformation number. 


By default, DEC GKS uses the range ([0,1] x [0,1]), in NDC coordinates, as 
the normalization viewport. 


DEC GKS maps the normalization window onto the viewport. The image 
retains its position in the viewport relative to its position in the window, 
but the image’s aspect ratio may differ. Also, if the image extends past 
the boundary of the window, it may or may not extend past the viewport 
boundary, depending on whether or not clipping is enabled or disabled. See 
Section 6.1 for more information concerning normalization transformations 
and clipping. 


GKS$SET_VIEWPORT (transformation_number, 
minimum_x_value, maximum_x_value, 
minimum_y_value, maximum_y_value) 


GSVP_(xform, xmin, xmax, ymin, ymax) 
gsetviewport (transform, viewport) 
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SET VIEWPORT 


Arguments 


transformation_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the normalization transformation number. Once you select 
this number by calling SELECT NORMALIZATION TRANSFORMATION, 
any subsequent calls to output functions use the window and viewport 
associated with this number. . 


minimum_x_value 


data type: real 
access: read-only 
mechanism: by reference 


This argument specifies the lower left corner point of the X value in a 
rectangular viewport. Make sure that the lower left corner is located 
within the default normalization viewport range. See Section 6.1 for more 
information concerning normalization transformations. 


maximum_x_value 


data type: real 
access: read-only 
mechanism: by reference 


This argument specifies the X value for the upper right corner of the 
viewport, and with the minimum X and Y values and maximum Y value, 
determines the rectangular area of the viewport within the NDC space. 
Make sure that the maximum X and Y values are located within the default 
normalization viewport boundaries. See Section 6.1 for more information 
concerning normalization transformations. 


minimum_y_value 


data type: real 
access: read-only 
mechanism: by reference 


This argument specifies the lower left corner point of the Y value in a 
rectangular viewport. Make sure that the lower left corner is located 
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SET VIEWPORT 


within the default normalization viewport range. See Section 6.1 for more 
information concerning normalization transformations. 


maximum_y_value 


data type: real 
access: read-only 
mechanism: by reference 


This argument specifies the Y value for the upper right corner of the 
viewport, and with the minimum X and Y values and maximum X value, 
determines the rectangular area of the viewport within the NDC space. 
Make sure that the maximum X and Y values are located within the default 
normalization viewport boundaries. See Section 6.1 for more information 
concerning normalization transformations. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_ 20 GKS not in proper state: GKS in 
the error state in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 
shall be in one of the states GKOP, 
WSOP, WSAC, or SGOP in routine 
KK 

50 GKS$_ERROR_50 Transformation number is invalid 
in routine **** 

51 GKS$_ERROR_51 Rectangle definition is invalid in 
routine **** 

52 GKS$_ERROR_52 Viewport is not within the 


~ Normalized Device Coordinate 
unit square in routine **** 
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Program Example 


Refer to Example 6-1 in this section for a program example using a call to 
SET VIEWPORT. 
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SET VIEWPORT INPUT PRIORITY 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET VIEWPORT INPUT PRIORITY specifies the input 
priority of a given normalization transformation. If during stroke or locator 
input DEC GKS encounters a point on overlapping viewports in the NDC 
space, the viewport input priority list determines which normalization 
transformation to use when transforming the point back to world coordinate 
space. 


By default, the normalization transformations are ordered in a sequential 
list so that the transformation number 0 is the highest priority transforma- 
tion, and the transformation number 255 is the lowest. When you request 
stroke or locator input, DEC GKS uses the viewport with the highest 
priority when transforming a point on overlapping viewports. 


To change the priority list using SET VIEWPORT INPUT PRIORITY, you 
specify a normalization transformation number whose priority is to be 
changed, specify an index transformation number, and specify whether the 
first transformation is the next higher or lower priority. 


See Section 6.1.2 for more information concerning input and overlapping 
viewports. 


GKS$SET_VIEWPORT_PRIORITY = (transformation_number, 
reference_trans_number, 
relative_priority) 


GSVPIP  (xform, ref_xform, rel_prior) 
gsetviewportinputpri (transform, reference, priority) 
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Arguments 
transformation_number 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the normalization transformation number whose priority 
you want to change. 


reference_trans_number 


data type: integer 
access: read-only 
mechanism: by reference 


This is a normalization transformation number to be used as a reference 
for changing the priority of the first transformation number. You specify 
whether or not the first number is of the next higher or lower priority than 
this reference number. If you specified lower, the first number is placed 
directly behind this reference number in the sequential priority list. If you 
specified higher, DEC GKS places the first number directly in front of this 
reference number in the sequential priority list. 


relative_priority 

data type: integer 
access: read-only 
mechanism: by reference 


This argument is a flag that determines whether or not the normalization 
transformation number is of higher or lower priority than the reference 
normalization transformation number. The argument can be any of the 
following values or constants: 


Value Constant Description 
0 GKS$K_INPUT_PRIORITY_HIGHER Higher priority 
1 GKS$K_INPUT_PRIORITY_LOWER Lower priority 
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Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
—24 DECGKS$_ERROR_NEG_24 
8 GKS$_ERROR_8 

50 GKS$_ERROR_50 


Program Example 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


Invalid value specified for view- 
port priority flag in routine **** 


GKS not in proper state: GKS 
shall be in one of the states GKOP, 
WSOP, WSAC, or SGOP in routine 


RRR 


Transformation number is invalid 
in routine **** 


Example 6-3 illustrates the use of the function SET VIEWPORT INPUT 
PRIORITY. Following the program example, Figure 6—11 illustrates the 


program’s effect on a VT241 workstation. 
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Example 6-3: Setting the Input Priority 


Cc This program accepts input twice from the same spot on the 
Cc workstation surface. When the input priority is changed, 
Cc the world coordinates returned are that of the other overlapping 
C viewport. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, ERROR_STATUS, INPUT MODE, ECHO FLAG, XFORM, 
* RECORD BUFFER_LENGTH, RECORD SIZE, INPUT_STATUS, DEFAULT, 
* LOW_LEFT CORNER, RIGHT_HALF, DEVICE_NUM, NUM_POINTS, 
* PROMPT ECHO TYPE, DATA_RECORD( 1 ) 
REAL WORLD_COORD_X, WORLD _COORD_Y, 
* ECHO AREA( 4 ), PX( 5 ), PY( 5 ), 
* LARGER 
DATA PX / 0.0, 1.0, 1.0, 0.0, 0.0 / 
DATA PY / 0.0, 0.0, 1.0, 1.0, 0.0 / 
DATA DEFAULT / 0 /, DEVICE_NUM / 1 /, LARGER / 0.04 /, 
* RIGHT HALF / 1 /, LOW_LEFT_CORNER / 1 /, NUM_POINTS / 5 /, 
* WS ID / 1 / 
CALL GKSSOPEN_GKS( ‘SYSS$ERROR:’ ) 
CALL GKSS$OPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKSS$ACTIVATE WS( WS_ID ) 
Cc When you outline the entire default world coordinate space, you 
Cc also outline the entire NDC space, the entire workstation window, 
Cc and the entire workstation viewport. 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 
C This window and viewport are associated with the 
Cc normalization transformation number 1. 
CALL GKS$SET_WINDOW( LOW_LEFT_CORNER, 0.0, 0.5, 0.0, 0.5 ) 
CALL GKS$SET_VIEWPORT( RIGHT_HALF, 0.5, 1.0, 0.0, 1.0 ) 
Cc Select the new transformation and outline the new windows 
Cc and viewports. 
CALL GKS$SELECT_XFORM( 1 ) 
CALL GKSS$POLYLINE( NUM_POINTS, PX, PY ) 
Cc Assign a value to RECORD _BUFFER_LENGTH: 4 bytes. On output, 
Cc this argument should contain the value 0 since 
c GKS$INQ_LOCATOR_STATE does not write anything to the buffer. 


RECORD_BUFFER_LENGTH = 4 
1] CALL GKS$INQ_LOCATOR_STATE( WS_ID, DEVICE_NUM, 


* GKS$K_VALUE_REALIZED, ERROR_STATUS, INPUT MODE, ECHO FLAG, 
* XFORM, WORLD COORD_X, WORLD COORD_Y, PROMPT _ECHO TYPE, 

* ECHO_AREA, DATA_RECORD, RECORD _BUFFER_LENGTH, 

* RECORD SIZE ) 





(continued on next page) 
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Example 6-3 (Cont.): Setting the Input Priority 


e PROMPT _ECHO TYPE = 1 
@ CALL GKSSINIT_LOCATOR( WS_ID, DEVICE_NUM, 0.7, 0.5, DEFAULT, 
* PROMPT ECHO TYPE, ECHO AREA, DATA_RECORD, 
* RECORD_BUFFER_LENGTH ) 
CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_ REQUEST, GKS$K_ECHO ) 
Cc KEREKEKEKKKKKKEKKKKEKKKKKKKKKKKKKKKKK 
Cc At this pause, just type RETURN. 
Cc KRHKKKKKEKKKEKKEKKEKKKKKKRKKKKKKKKKKKKK 


CALL GKSSREQUEST_LOCATOR( WS_ID, DEVICE_NUM, INPUT_STATUS, 
* XFORM, WORLD COORD_X, WORLD_COORD Y ) 
Cc Write the returned world coordinates. 
WRITE(5, *) WORLD COORD _X, WORLD COORD_Y 
CALL GKS$SELECT_XFORM ( DEFAULT ) 
CALL GKSS$SET_TEXT_HEIGHT( LARGER ) 
CALL GKSSTEXT( 0.01, 0.4, ‘’Higher priority VP: 0’ ) 


Set the current viewport (associated with the selected 
transformation number 1) to be a higher priority than the 
default viewport. 


5) CALL GKS$SET_VIEWPORT_PRIORITY( RIGHT HALF, DEFAULT, 
* GKS$K_INPUT PRIORITY HIGHER ) 


ana 


Cc Call for input from the same spot. 
@ CALL GKSSINIT_LOCATOR( WS_ID, DEVICE_NUM, 0.7, 0.5, DEFAULT, 
* PROMPT ECHO TYPE, ECHO AREA, DATA RECORD, 
* RECORD _BUFFER_LENGTH ) 
CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 
x GKS$K_INPUT_MODE_REQUEST, GKS$K_ECHO ) 


(continued on next page) 
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6—40 


Example 6-3 (Cont.): Setting the Input Priority 


Cc 
Cc 
Cc 


aa 


KEKKKKKKKKKKREKKKKEKKKEKKKKKKKKKKKK 


At this pause, just type RETURN. 
KRREKKKKEKKEKEKKKKEKKKKKEKKERKKKKKEKEKK 

CALL GKS$REQUEST_LOCATOR( WS_ID, DEVICE_NUM, INPUT STATUS, 
* XFORM, WORLD _COORD_X, WORLD COORD Y ) 


Write the returned world coordinates, this time from the smaller 
viewport on the right half of the screen. 

WRITE(5, *) WORLD COORD X, WORLD _COORD_Y 

CALL GKSSSELECT XFORM( DEFAULT ) 


CALL GKSSTEXT( 0.01, 0.3, ‘Higher priority VP: 1’). 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 

CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 
@ The function INQUIRE LOCATOR DEVICE STATE enables you to 


change the input data record and other pertinent values that are needed 
to perform locator input. Locator input returns a single world coordi- 
nate point. For more information concerning the types of input in DEC 
GKS, refer to Chapter 7, Input Functions. For more information con- 
cerning the arguments to INQUIRE LOCATOR DEVICE STATE, refer 
to Chapter 11, Inquiry Functions in Part 2 of the DEC GKS Reference 
Manual. 


The prompt and echo types are device independent. Depending on the 
type of prompt and echo type you choose, you may or may not need to 
pass an input data record. 


In this example, the type of prompt echo is a tracking plus sign. When 
using this prompt and echo type, pass a dummy data record; DEC GKS 
does not use the record. For more information, refer to Chapter 7, Input 
Functions. 


The function INITIALIZE LOCATOR sets the initial values needed to 
perform locator input, including the position in world coordinates, on 
which to place the tracking plus sign. This call places the plus sign on 
the world coordinate (0.7, 0.5). For more information, refer to Chapter 7, 
Input Functions. 
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© The function SET LOCATOR MODE sets the operating mode of a specific 
locator class device and allows DEC GKS to accept input. At this point 
in the program, just press the RETURN key. The program returns the 
world coordinates from the viewport associated with the transformation 
number with the higher priority, unity transformation number 0. For 
more information, refer to Chapter 7, Input Functions. 


© When you last requested input, the normalization transformation num- 
ber 0 had higher priority. Consequently, the wore coordinates returned 
were from the default window. 


To return world coordinates from the window in the lower left corner of 
the world coordinate plane, whose viewport overlaps the default viewport 
on the right side of the NDC plane, give the transformation number 1 
the higher priority. 

© When you initialize the tracking plus sign to the exact same spot on 
the workstation surface, and when you request locator input again, the 
program returns different world coordinates; it returns the world coordi- 
nates from the overlapping viewport associated with the normalization 
transformation number 1. 


Figure 6—11 shows the screen of a VT241 terminal after the program has 
run to completion. 
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Figure 6-11: Setting the Input Priority—VT241 
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SET WINDOW 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET WINDOW associates normalization window boundaries 
on the world coordinate plane with a specified normalization transformation 
number. 


By default, DEC GKS uses the range ([0,1] x [0,1]), in world coordinates, as 
the normalization window. 


DEC GKS maps the normalization window onto the viewport. The image 
retains its position in the viewport relative to its position in the window, 
but the image’s aspect ratio may differ. Also, if the image extends past the 
boundary of the world window, it may or may not extend past the viewport 


boundary, depending on whether or not clipping is enabled or disabled. See 


Section 6.1 for more information concerning normalization transformations 
and clipping. 


GKS$SET_WINDOW  (transformation_number, 
minimum_x_value, maximum_x_ value, 
minimum_y_value, maximum | y_value) 


GSWN _(xform, xmin, xmax, ymin, ymax) 
gsetwindow (iransform, window) 


Transformation Functions 6-43 


SET WINDOW 


Arguments 
transformation_number 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the normalization transformation number. Once you select 
this number by calling SELECT NORMALIZATION TRANSFORMATION, 
any subsequent calls to output functions use the window and viewport 
associated with this number. 


minimum_x_value 


data type: real 
access: read-only 
mechanism: by reference 


This argument specifies the lower left corner point of the X value in a 
rectangular window. 


maximum_x_value 


data type: real 
access: read-only 
mechanism: by reference 


This argument specifies the X value for the upper right corner of the window, 
and with the minimum X and Y values and maximum Y value, determines 
the rectangular area of the window within the world coordinate space. 


1 


minimum_y_value 


data type: real 
access: read-only 
mechanism: by reference 


This argument specifies the lower left corner point of the Y value in a 
rectangular window. 


6—44 Transformation Functions 


maximum_y_value 


data type: real 
access: read-only 
mechanism: by reference 


SET WINDOW 


This argument specifies the Y value for the upper right corner of the window, 
and with the minimum X and Y values and maximum X value, determines 
the rectangular area of the window within the world coordinate space. 


Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
8 GKS$_ERROR_8 

50 GKS$_ERROR_50 

51 GKS$_ERROR_51 


Program Example 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be in one of the states GKOP, 
WSOP, WSAC, or SGOP in routine 


BRE 


_ Transformation number is invalid 


in routine **** 


Rectangle definition is invalid in 
routine **** 


Refer to Example 6—1 in this section for a program example using a call to 


SET WINDOW. 
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SET WORKSTATION VIEWPORT 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET WORKSTATION VIEWPORT establishes the portion of 
the workstation surface on which DEC GKS maps the workstation window. 


The default workstation viewport is the largest square on the workstation 
surface, beginning with the lower left corner. If you define a new worksta- 
tion viewport or window such that the two are not proportionally equivalent, 
DEC GKS may not use the entire viewport. DEC GKS only uses the portion 
of the viewport that maintains the shape of the picture in the workstation 
window. See Section 6.2 for detailed information. 


NOTE 


If your workstation cannot implement an immediate change to 
the workstation window or viewport, the surface needs to be 
regenerated to establish the requested settings. If the surface 
is regenerated, the surface is cleared and only output primitives 
stored in segments are redrawn. You lose any primitives not 
contained in segments. For a detailed discussion of surface 
regeneration, refer to Chapter 3, Control Functions. 


GKS$SET_WS VIEWPORT (workstation_id, 
minimum_x_value, 
maximum_x_value, 
minimum_y_value, 
maximum_y_value) 


GSWKVP _  (workstation_id, xmin, xmax, ymin, ymax) 
gsetwsviewport (workstation_id, viewport) 
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Arguments 


workstation_id 


data type: integer 

access: read-only 

mechanism: by reference 

This argument is a workstation identifier specified in a previous call to 
OPEN WORKSTATION. 


minimum_x_value 


data type: real 
access: read-only 
mechanism: by reference 


This argument specifies the lower left corner point of the X value in a 
rectangular workstation viewport. Make sure that this point is located 
within the display surface limits of the specified workstation. You should 
use the function INQUIRE DISPLAY SPACE SIZE, which returns the 
maximum X and Y values of the workstation display surface. (For more 
information, refer to Chapter 11, ney Functions.) 


maximum_x_value 


data type: real 
access: read-only 
mechanism: ' by reference 


This argument specifies the X value for the upper right corner of the 
viewport, and with the minimum X and Y values and maximum Y value, 
determines the rectangular area of the workstation viewport within the 
device coordinate space. Make sure that the maximum X and Y values are 
located within the display surface limits of the specified workstation. You 
should use the function INQUIRE DISPLAY SPACE SIZE, which returns 
the maximum X and Y values of the workstation display surface. (For more 
information, refer to Chapter 11, Inquiry Functions.) 
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minimum_y_value 


data type: real 
access: read-only 
mechanism: by reference 


This argument specifies the lower left corner point of the Y value in a 
rectangular workstation viewport. Make sure that this point is located 
within the display surface limits of the specified workstation. You should 
use the function INQUIRE DISPLAY SPACE SIZE, which returns the 
maximum X and Y values of the workstation display surface. (For more 
information, refer to Chapter 11, Inquiry Functions.) 


maximum_y_value 


data type: real 
access: read-only 
mechanism: by reference 


This argument specifies the Y value for the upper right corner of the 
viewport. With the minimum X and Y values and maximum X value, it 
determines the rectangular area of the workstation viewport within the 
device coordinate space. Make sure that the maximum X and Y values are 
located within the display surface limits of the specified workstation. You 
should use the function INQUIRE DISPLAY SPACE SIZE, which returns 
the maximum X and Y values of the workstation display surface. (For more 
information, refer to Chapter 11, Inquiry Functions.) 


Error Messages 


Error Completion 

Number Status Code Message 

~20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state: GKS 


shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 
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Error 
Number 


20 


25 


33 


36 


51 


54 


Program Example 


Completion 
Status Code 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_33 


GKS$_ERROR_36 


GKS$_ERROR_51 


GKS$_ERROR_54 


SET WORKSTATION VIEWPORT 


Message 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is of cate- 
gory MI in routine **** 


Specified workstation is 
Workstation Independent Segment 
Storage in routine **** 


Rectangle definition is invalid in 
routine **** 


Workstation viewport is not within 
the display space in routine **** 


Example 6—4 illustrates the use of the function SET WORKSTATION 
VIEWPORT. Following the program example, Figure 6—12 illustrates the 


program’s effect on a VT241 workstation. 
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Example 6-4: Establishing a Workstation Viewport 


aQaaQqada 


aqaaa 


aaa 


This program uses the default normalization transformations, 
generates the "tall, thin house," updates the screen, 
changes the workstation viewport to the lower left 

corner of the VT241 surface, and generates the output again. 
IMPLICIT NONE 

INCLUDE ’SYS$LIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, NUM_POINTS, RASTER_Y, ERROR, METERS, 

* RASTER _X, DEFAULT 

REAL: PX ( 9 ), PY (9), PX_2 (5), PY_2 (5), 

* DEVICE _MAX X, DEVICE _MAX Y 


DATA PX / .4, .1, .1, .4, .25, .1, .4, .4, .1 / 
DATA PY / .1, .1, .7, «7, «9, «7, 1, «7, «1 / 
DATA PX_2 / 0.0, 1.0, 1.0, 0.0, 0.0 / 
DATA PY 2 / 0.0, 0.0, 1.0, 1.0, 0.0 / 


DATA NUM_POINTS / 9 /, WS_ID / 1 / 


CALL GKS$OPEN_GKS( ’SYS$ERROR:’ ) 
CALL GKSSOPEN WS( WS_ID, GKS$K_CONID_ DEFAULT 
CALL GKS$ACTIVATE WS( WS_ID ) 


GKS$K_VT240 ) 


Outlining the default world window will result in the outlining of 
the NDC plane, the workstation window, and the workstation 
viewport, by default. 

CALL GKSSPOLYLINE( 5, PX_2, PY_2 ) 


CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 

Release deferred output. Pause. Type RETURN when you are finished 
viewing the screen. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 

CALL GKSS$INQ_MAX DS_SIZE( GKS$K_VT240, ERROR, METERS, 

* DEVICE MAX X, DEVICE_MAX Y, RASTER_X, RASTER_Y ) 


CALL GKS$SET_WS_VIEWPORT( WS_ID, 0.0, DEVICE _MAX X/2.0, 
* 0.0, DEVICE_MAX Y¥/2.0 ) 


Update the screen so that the workstation can use the 
new workstation viewport (as noted in the function 
description section). 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM_FLAG ) 


Outline the default windows and viewports and draw the house again. 
CALL GKSSPOLYLINE( 5, PX_2, PY_2 ) 
CALL GKSSPOLYLINE( NUM_POINTS, PX, PY ) 





(continued on next page) 
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Example 6-4 (Cont.): Establishing a Workstation Viewport 


CALL GKSS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ PX contains the house’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the lower right corner of the house (0.4, 0.1). 


@ This code assumes the default normalization transformation. DEC GKS 
maps the default window to the default viewport, and then maps the 
default workstation window to the default viewport. 


© The function INQUIRE DISPLAY SPACE SIZE returns the maximum X 
and Y display surface coordinates in the arguments device_max_x and 
device_max_y. For more information concerning the other arguments, 
refer to the INQUIRE DISPLAY SPACE SIZE function description in 
Chapter 11, Inquiry Functions. 

@ The function SET WORKSTATION VIEWPORT changes the worksta- 
tion viewport to the lower left corner of the screen. The picture being 
displayed is still the same (the default workstation window), but the 
space on the workstation surface used to display the same picture has 
changed. 


Figure 6-12 shows the screen of a VT241 terminal after the program has 
run to completion. 
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Figure 6-12: Establishing a Workstation Viewport—VT241 
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SET WORKSTATION WINDOW 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET WORKSTATION WINDOW establishes the portion of the 
composed picture (on the NDC plane) that DEC GKS maps to the current 
workstation viewport. Despite the current value of the clipping flag, DEC 
GKS clips all pictures at the workstation window boundary. 


By default, DEC GKS uses the entire picture, mapping the default work- 
station window range ([0,1] x [0,1]), onto the largest square that the 
workstation can produce. 


NOTE 


If your workstation cannot implement an immediate change to 
the workstation window or viewport, the surface needs to be 
regenerated to establish the current settings. If the surface is 
regenerated, the surface is cleared and only output primitives 
stored in segments are redrawn. You lose any primitives not 
contained in segments. For a detailed discussion of surface 
regeneration, refer to Chapter 3, Control Functions. 


GKS$SET_WS_WINDOW § (workstation_id, minimum_x_value, 
| maximum_x_value, minimum_y_value, 
maximum_y_value) 


GSWKWN_ = (workstation_id, xmin, xmax, ymin, ymax) 
gsetwswindow (workstation_id, window) 
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Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 
This argument is a workstation identifier specified in a previous call to 
OPEN WORKSTATION. 


minimum_x_value 


data type: real 
access: read-only 
mechanism: by reference 


This argument specifies the lower left corner point of the X value in a 
rectangular workstation window, in NDC points. Make sure that this point 
is located within the default workstation window boundary. See Section 6.2 
for more information concerning workstation transformations. 


maximum_x_value 


data type: real 
access: read-only 
mechanism: by reference 


This argument specifies the lower left corner point of the Y value in a 
rectangular workstation window, in NDC points. Make sure that this point 
is located within the default workstation window boundary. See Section 6.2 
for more information concerning workstation transformations. 


minimum_x_value 


data type: integer 
access: read-only 
mechanism: by reference 


This argument specifies the upper right corner of the X value of the window, 
and used with the maximum X and Y values, and the minimum Y value, 
determines the rectangular area of the workstation window within the NDC 
space. Make sure that the maximum X and Y values are located within the 
default workstation window boundary. See Section 6.2 for more information 
concerning workstation transformations. 
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minimum_y_value 


data type: integer 
access: read-only 
mechanism: by reference 


This argument specifies the upper right corner of the Y value of the window, 
and used with the maximum X and Y values, and the minimum X value, 
determines the rectangular area of the workstation window within the NDC 
space. Make sure that the maximum X and Y values are located within the 
default workstation window boundary. See Section 6.2 for more information 
concerning workstation transformations. 


Error Messages 


Error Completion 

Number Status Code Message . 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 

20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 

25 GKS$_ERROR_25 Specified workstation is not open 
in routine **** 

33 GKS$_ERROR_33 Specified workstation is of cate- 


gory MI in routine **** 
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Error Completion 

Number Status Code Message 

36 GKS$_ERROR_36 Specified workstation is 
Workstation Independent Segment 
Storage in routine **** 

51 GKS$_ERROR_51 Rectangle definition is invalid in 
routine **** 

53 GKS$_ERROR_53 Workstation window is not within 


the Normalized Device Coordinate 
unit square in routine **** 


Program Example 


Example 6—5 illustrates the use of the function SET WORKSTATION 
WINDOW. Following the program example, Figure 6-13 illustrates the 
program’s effect on a VT241 workstation. 


Example 6-5: Establishing a Workstation Window 


This program uses the default normalization transformations, 
generates the "tall, thin house," updates the screen, 
changes the workstation window to the lower half of the 
default workstation window, and generates the output again. 
IMPLICIT NONE 

INCLUDE ’SYSS$LIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, NUM_POINTS, DEFAULT 


0 REAL PX (9), PY (9), PX2 (5), PY2(5) 
DATA PX .4p sty chp ade «eo ats why dhol 7 
DATA RY: slip lp cl ae 28. ole ln ely 4d 
DATA PX 2 / 0.0, 1.0, 1.0, 0.0, 0.0 / 
DATA PY 2 / 0.0, 0.0, 1.0, 1.0, 0.0 / 
DATA NUM POINTS / 9 /, DEFAULT / 0 /, WS_ID / 1 / 


aaAaAaAAN 


CALL GKSSOPEN_GKS( ‘SYSSERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKSS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


(continued on next page) 
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Example 6—5 (Cont.): Establishing a Workstation Window 


aaa 


Outlining the default world window will result in the outlining of 
the NDC plane, the workstation window, and the workstation 
viewport, by default. 

CALL GKSSPOLYLINE( 5, PX_2, PY 2 ) 


CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 

Release deferred output. Pause. Type RETURN when you are finished 
viewing the screen. 

CALL GKS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 

Set a new workstation window that is the lower half of the 

default workstation window. 

CALL GKS$SET_WS WINDOW( WS_ID, 0.0, 1.0, 0.0, 0.5 ) 


UPDATE the surface so that DEC GKS can use the new 
workstation window (as noted in the function description 
section). 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM FLAG ) 


Outline the default NDC space and draw the house again. 
CALL GKS$POLYLINE( 5, PX_2, PY_2 ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 

CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


PX contains the house’s X world coordinate values and PY contains the 
Y world coordinate values. For example, the first element in both arrays 
specifies the lower right corner of the house (0.4, 0.1). 


This code assumes the default normalization transformation. DEC GKS 
maps the default window to the default viewport and then maps the 
default workstation window to the default workstation viewport. 


The function SET WORKSTATION WINDOW changes the workstation 
window to be the lower half of the NDC space. The picture is now 
half of what it was and will now be mapped onto the largest rectangle 
on the display surface, starting at lower left point within the current 
workstation viewport, that maintains the aspect ratio. Notice how DEC 
GKS does not map the current workstation window onto the entire 
workstation viewport, so as to maintain the shape of the picture. 
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Figure 6-13 shows the screen of a VT241 terminal after the program has 
run to completion. 


Figure 6-13: Establishing a Workstation Window—VT241 
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Chapter 7 


Input Functions 


The DEC GKS input functions allow an application program to accept input 
from a user. The following list presents the input functions by category: 


Category 


Initialization 


Mode Control 


Request Mode 


Sample Mode 


GKS Functions 


INITIALIZE CHOICE 
INITIALIZE LOCATOR 
INITIALIZE PICK 
INITIALIZE STRING 
INITIALIZE STROKE 
INITIALIZE VALUATOR 


SET CHOICE MODE 
SET LOCATOR MODE 
SET PICK MODE 

SET STRING MODE 
SET STROKE MODE 
SET VALUATOR MODE 


REQUEST CHOICE 
REQUEST LOCATOR 
REQUEST PICK 
REQUEST STRING 
REQUEST STROKE 
REQUEST VALUATOR 


SAMPLE CHOICE 
SAMPLE LOCATOR 
SAMPLE PICK 
SAMPLE STRING 
SAMPLE STROKE 
SAMPLE VALUATOR 
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Category GKS Functions 


Event Mode AWAIT EVENT 
FLUSH DEVICE EVENTS 
GET CHOICE 
GET LOCATOR 
GET PICK 
GET STRING 
GET STROKE 
GET VALUATOR 


7.1. Physical and Logical Input Devices 


7-2 


There are many physica] devices that can provide input to a program. 
Common physical devices include a terminal keyboard, a tablet, and a 
mouse. You can translate the information obtained from these physical 
devices in several ways. For instance, a letter typed at the keyboard can 
represent a decimal ASCII value, a character value, a character string 
containing one letter, or many other values depending on how the program 
stores and then interprets the input. 


Similarly, DEC GKS accepts several types of input. DEC GKS accepts real 
numbers (as real values, coordinate points, or as a series of coordinate 
points), integers (as choice numbers, segment names, or pick identifiers), 
and character strings. To translate and store input from the physical devices 
according to the DEC GKS data types, DEC GKS defines logical input 
devices. Logical input devices are abstractions of the physical input devices 
that allow the user to input data, using a similar visual interface, despite 
the differences in physical devices. The value returned from a logical input 
device is called the device’s measure. 


DEC GKS defines the logical input devices by the following components: 


¢ A workstation identifier 
e An input class 
¢ A logical device number 


The following sections discuss each component in detail. 


Input Functions 


7.1.1 The Workstation Identifier 


The workstation identifier specifies an open workstation, of category 
GKS$K_WSCAT_INPUT or GKS$K_WSCAT_OUTIN, on which one or 
more physical input devices are present. For instance, a single workstation 
supporting input may use both a mouse and a keyboard for input. 


The capabilities of a specified workstation determine the prompt and echo 
types available, and the methods used for signaling the acceptance of an 
input value (called input triggers). A cursor is an example of a prompt (see 
Section 7.2 for a detailed discussion of prompts and echo types). Pressing 
the RETURN key to signal the acceptance of a value is an example of a 
trigger. 


7.1.2 The Input Class 


The input class is the second input component, and it tells DEC GKS the 
data type of the information to be entered. The six input classes are as 


follows: 

e¢ Locator 
e Stroke 

¢ Valuator 
¢ Choice 

¢ String 

e =6Pick 


A locator class device first positions a prompt on the workstation surface. 
The user can then move the prompt (on a VT241, the user can press the 
arrow keys), and if you are using an applicable input mode, trigger the 
input device (on a VT241, by pressing the RETURN key). This input 

class returns two real numbers that represent world coordinate values. 
DEC GKS transforms the input point from a device coordinate point to a 
normalized device coordinate (NDC) point, and then from an NDC point to a 
corresponding world coordinate point. 


A stroke class device also positions a prompt on the workstation surface. 
The user can then move the prompt (on a VT241, by pressing the arrow 
keys) and, when choosing a desired device coordinate point, the user signals 
DEC GKS (on a VT241, by pressing the space bar; on the VAXstations, you 
specify a distance vector and the user enters points by pressing a button on 
the mouse). The user keeps choosing points until the desired sequence is 
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entered. This input class returns a sequence of real numbers that are the 
corresponding world coordinate values of the stroke. DEC GKS transforms 
the input points from device coordinate points to NDC points, and then from 
NDC points to corresponding world coordinate points. 


For more information concerning the DEC GKS coordinate systems, refer to 
Chapter 6, Transformation Functions. 


A valuator class device creates a picture on the workstation surface that 
represents a real number or a series of real number values. You specify the 
lowest and highest values. For several workstations, the valuator class may 
look like a radio dial with a pointer to a current value. The user moves the 
cursor up and down the scale (on a VT241, using the arrow keys) until it is 
positioned as desired (on a VT241, pressing the RETURN key can trigger 
this class of device). This input class returns the real number representing 
the pointer’s last position on the scale. 


A choice class device creates a picture on the workstation surface that lists 
a series of choices. The user sees the choices as the application programmer 
labels them; the choices are represented internally by integer values. For 
several workstations, the choices can look like a menu, with the currently 
selected choice highlighted (on a VT241, in complement mode). The user 
moves among the choices (on a VT241, by pressing the arrow keys) until the 
user’s choice is highlighted. When triggered (on a VT241, by pressing the 
RETURN key), this input class returns the integer representing the selected 
choice. 


A string class device creates an area on the workstation surface on which 
the user can enter a character string. Optionally, you can provide an initial 
string to prompt the user. DEC GKS appends the input string to the initial 
string. The user can enter a string as large as the defined input buffer. On 
many workstations, pressing the RETURN key can trigger the string input 
devices. 


A pick class device positions a prompt on the workstation surface. The user 
moves the prompt among the segments on the workstation surface (on a 
VT241, by using the arrow keys), and if you are using an applicable input 
mode, the user can trigger the device (on a VT241, by pressing the RETURN 
key). The pick device returns integers that represent the name of the picked 
segment or the pick identifier associated with portions of a segment. (For 
detailed information concerning pick identifiers, refer to Chapter 8, Segment 
Functions.) 
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Figure 7—1 illustrates possible visual interfaces for the logical input classes. 


Figure 7-1: Logical Input Classes 
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Differences between workstations’ implementations of logical input 

classes may be significant. For example, using a stroke input device on 

a VAXstation, you can specify X and Y device coordinate change vectors to 
tell the graphics handler when to add another device coordinate point to the 
stroke. When the user specifies a point whose distance from the last entered 
point exceeds both the specified X and Y vectors, the input device accepts 
the point as the next point in the stroke. This affects the smoothness of the 
line, allowing you to create relatively curved shapes instead of jagged lines. 
If you specify a relatively short X and Y difference, DEC GKS accepts many 
of the input points as you move the mouse. 
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In contrast, on the VT241, you must move the arrow keys and signal each 
time you have reached a point you want to be a part of the stroke. If the 
point exceeds the X and Y change vector values, then the graphics handler 
accepts the points. 


7.1.3 The Device Number 


DEC GKS also uses the logical device number to differentiate between 
various methods of entering the same class of data on the same workstation. 
For instance, a workstation may use both the mouse and the arrow keys on 
a keyboard as two distinct stroke logical input devices. You can distinguish 
between the two input devices by their logical device number. For instance, 
the graphics handler could assign the logical device number 1 to the stroke 
device using the mouse, and could assign the number 2 to the stroke device 
using the arrow keys on the keyboard. When you request input on such a 
workstation, you specify whether you wish to use stroke logical input device 
1 or 2 (the mouse or the keyboard). The application programmer needs 
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to tell the user which physical devices (such as keyboard keys, or mouse 
buttons) control the particular logical input device. 


7.2 Prompt and Echo Types 
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There are differences in the way a single workstation can prompt the user 
and can echo the input when using the same logical device. Some differences 
may be subtle. For example, a workstation may use either a plus sign or 

a set of cross hairs as a prompt for a single locator device, both triggered 

by pressing the RETURN key. To distinguish between different visual 
interfaces available for a single logical input device, that device can have a 
number of prompt and echo types. 


For example, the VT241 graphics handler accepts seven different prompt 
and echo types for its locator input devices. The prompt can be any of the 
following: 


¢ A box (similar in appearance to the pick aperture used for pick input) 
e A tracking plus sign (+) 

¢ Across hair 

e A tracking cross (X) 

¢ Aline from the initial locator position to the current locator position 
¢ A rectangle whose diagonal connects the initial and current positions 
e A numeric representation of the current locator position 


Since the graphics handlers use DEC GKS primitives such as lines, markers, 
and fill areas to construct input prompts, the graphics handler optionally 
uses additional information that determines how the prompt and echoed 
input appear on the surface. For instance, a handler may use a polyline 
output attribute that would affect the appearance of cross hairs on the 
surface. The requirements depend on the needs of the different prompt and 
echo types on different physical devices. 


To pass information to meet the requirements of a certain prompt and echo 
type on a given logical input device, you use the input data record. You can 
either use the default data record or specify a new data record to one of the 
input initializing functions (INITIALIZE LOCATOR, INITIALIZE STROKE, 
and so forth). 


See Section 7.2.1 for a detailed discussion of input data records. To review 
the available prompt and echo types for a given logical input device on 
your workstation, use the appropriate workstation description table inquiry 
function or refer to Appendix J, DEC GKS Specific Input Values. 
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7.2.1 


Input Data Records 


Due to the needs of a given prompt and echo type for a logical input class, 
you need to pass an input data record if you choose to call one of the 
initializing input functions (INITIALIZE LOCATOR, INITIALIZE STROKE, 
and so forth). The data record contains information relevant to the input 
prompt interface. For instance, the input data record for a locator logical 
input device may specify output attributes that affect the thickness or color 
of cross hairs on the workstation surface. 


When the GKS standard describes the input data records, it specifies 
required and not required components of the data record. If a component 
is required, you can be certain that all GKS graphics handlers use that 
component of the data record. If an input data record component is not 
required, the device handler must be able to accept that component, but 
may or may not use that component when generating the input prompt 
and echo. For instance, if polyline color is not a required part of the data 
record, the GKS implementation cannot generate an error if it encounters 
the component and does not have to change the color of the prompt on the 
workstation surface. 


NOTE 


In almost all cases, the DEC GKS supported graphics handlers 
require that you pass the complete GKS standard data record. 
Depending on the device, the graphics handler may or may not 
use all the components. For variable-length data records, you 
must be sure to pass the correct size of the data record. For 
detailed information concerning the required data record size, 
the initial data record values, or the components actually used — 
by a particular graphics handler, refer to Appendix J, DEC GKS 
Specific Input Values. 


The following sections describe the input data records defined by the GKS 
standard. Input data records are defined according to the logical input 
class and the prompt and echo type. The tables list the GKS standard data 
records. The column labelled Required either contains an R for required or 
an N for nonrequired. If you have a general understanding of input data 
records, you may only need to skim these sections. 
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Choice Class 


Choice Class 


The GKS standard defines the following prompt and echo type values: 


Echo 

Type 

Number Description 

1 Designate the current choice integer value using an implementation- 
specific technique. The device can use any portion of the data record 
(for information specific to your device, refer to the DEC GKS Device 
Specifics Reference Manual.) 

2 Use the device’s capability for prompting. GKS compares the number of 
prompts requested with the number of maximum prompts on the device. 
The data record specifies whether each prompt is turned on or turned 
off. 

3 Using an appropriate technique, allow the user to select one of a group 
of choices, each choice labeled with a string. 

4 Using an alphanumeric keyboard, allow the user to select one of a group 
of choices, each choice labeled with a string. 

5 Map a segment to the echo area and map the segment’s pick identifiers 
to a numeric choice value. 


Prompt and echo type numbers greater than or equal to the number 6 are 


reserved for future standardization. Numbers less than or equal to 0 are 
device dependent. 


Choice Class: Prompt and Echo Type 1 


The GKS standard does not define a data record for this prompt and echo 
type. The format of the record is device dependent. 
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Choice Class 


Choice Class: Prompt and Echo Type 2 


Position Data Type Required Description 


1 Integer R Number of choice alternatives. 


2 Array (integer) R Array of prompts turned either on or off. 
GKS$K_CHOICE_PROMPT_ON (0) or 
GKS$K_CHOICE_PROMPT_OFF (1 ). 


Choice Class: Prompt and Echo Types 3 and 4 


Position Data Type Required Description 


1 Integer R Number of choice strings. 
2 Array R Array of strings as choice labels. 
(string) 
NOTE 


DEC GKS supported graphics handlers implement the data record 
for choice prompt and echo type 3 using three components instead 
of two. For detailed information, refer to Appendix J, DEC GKS 
Specific Input Values. 
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Choice Class 


Choice Class: Prompt and Echo Type 5 


Position Data Type Required Description 

1 Integer R Segment name. 

2 Integer R Number of choice alternatives. 
3 Array (integer) R Array of pick identifiers. 
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Locator Class 





Locator Class 


The GKS standard defines the following prompt and echo type values: 


Echo 

Type 

Number Description 

1 Mark the current location in an implementation-specific manner. The 
device can use any portion of the data record (for information specific to 
your device, refer to the DEC GKS Device Specifics Reference Manual.) 

2 Mark the current location by using a vertical and horizontal line as 
cross hairs. 

3 Mark the current location using a tracking cross. . 
Mark the current location using a line connecting the current location to 
the initial location. 

5 Mark the current location using a rectangle whose diagonal is the 
current location and the initial location. 

6 Mark the current location by displaying a digital representation of the 


location. 
Prompt and echo type numbers greater than or equal to the number 7 are 


reserved for future standardization. Numbers less than or equal to 0 are 
device dependent. 


Locator Class: Prompt and Echo Types 1, 2, 3, 6 


The GKS standard does not define a data record. You pass a null data 
record to the initializing input function. 
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Locator Class 


Locator Class: Prompt and Echo Type 4 


Data 
Position Type Required Description 
1 Integer N Attribute control flag. GKS$K_ACF_CURRENT 


(0) or GKS$K_ACF_SPECIFIED (1). Use the 
currently set output attributes or specify new 
attributes in this data record. 


If component 1 is GKS$K_ACF_SPECIFIED: 


Data 

Position Type Required Description 

2 Integer N Line type aspect source flag. GKS$K_ASF_ 
BUNDLED (0) or GKS$K_ASF_INDIVIDUAL 
(1). 

3 Integer N Line width scale factor aspect source flag. 
GKS$K_ASF_BUNDLED (0) or GKS$K_ASF_ 
INDIVIDUAL (1). 

4 Integer N Polyline color index aspect source flag. 
GKS$K_ASF_BUNDLED (0) or GKS$K_ASF_ 
INDIVIDUAL (1). 

5 Integer N Polyline index. 

6 Integer N Line type index. 

7 Real N Line width scale factor. 

8 Integer N Polyline color index. 
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Locator Class 


Locator Class: Prompt and Echo Type 5 


Data 
Position Type 
1 Integer 
2 Integer 


Required Description 


N 


N 


Polyline/fill area control flag. GKS$K_ACF_ 
POLYLINE (0) or GKS$K_ACF_FILL_AREA 
(1). Use a polyline or a filled area to draw the 
rectangle whose diagonal connects the current 
and initial points. 

Attribute control flag. GKS$K_ACF_CURRENT 
(0) or GKS$K_ACF_SPECIFIED (1). Use the 
currently set output attributes or specify new 
attributes in this data record. 


If component 1 is GKS$K_ACF_POLYLINE and component 2 is GKS$K_ 


ACF_SPECIFIED: 


Data 
Position Type 
3 Integer 
4 Integer 
5 Integer 
6 Integer 
7 Integer 
8 Real 
9 Integer 


Required Description 


N 


Z 


N 
N 
N 
N 


Line type aspect source flag. GKS$K_ASF_ 
BUNDLED (0) or GKS$K_ASF_INDIVIDUAL 
(1). 


Line width scale factor aspect source flag. 
GKS$K_ASF_BUNDLED (0) or GKS$K_ASF_ 
INDIVIDUAL (1). 


Polyline color index aspect source flag. 
GKS$K_ASF_BUNDLED (0) or GKS$K_ASF_ 
INDIVIDUAL (1). 


Polyline index. 
Line type index. 
Line width scale factor. 


Polyline color index. 


If component 1 is GKS$K_ACF_FILL_AREA and component 2 is GKS$K_ 


ACF_SPECIFIED: 
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Locator Class 
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Data 
Position Type 
3 Integer 
4 Integer 
5 Integer 

Integer 
7 | Integer 
8 Integer 
9 Integer 


Input Functions 


Required Description 


N 


Fill area interior style aspect source flag. 
GKS$K_ASF_BUNDLED (0) or GKS$K_ASF_ 
INDIVIDUAL (1). 


Fill area style index aspect source flag. 
GKS$K_ASF_BUNDLED (0) or GKS$K_ASF_ 
INDIVIDUAL (1). 


Fill area color index aspect source flag. 
GKS$K_ASF_BUNDLED (0) or GKS$K_ASF_ 
INDIVIDUAL (1). 


Fill area index. 


Fill area interior style. GKS$K_INTSTYLE_ 
HOLLOW (0), GKS$K_INTSTYLE_SOLID (1), 
GKS$K_INTSTYLE_PATTERN (2), or GKS$K_ 
INTSTYLE_HATCH (3). 


Fill area style index. 
Fill area color index. 


Pick Class 


Pick Class 


The GKS standard defines the following prompt and echo type values: 


Echo 

Type 

Number Description 

1 Use an implementation-defined technique to highlight at least the 

: picked primitive. The device can use any portion of any of the data 
record (for information specific to your device, refer to the DEC GKS 
Device Specifics Reference Manual.) 

2 Echo the group of primitives that share the same pick identifier as the 
picked primitive. 

3 Echo the whole segment containing the picked primitive. 


Prompt and echo type numbers greater than or equal to the number 4 are 
reserved for future standardization. Numbers less than or equal to 0 are 
device dependent. 


Pick Class: All Prompt and Echo Types 


The GKS standard does not define a data record for this logical input device. 
The pick data record is device dependent. 
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String Class 


String Class 


The GKS standard defines the following prompt and echo type values: 


Echo 
Type 


Number Description 
1 Display the current string value in the echo area. 
Prompt and echo type numbers greater than or equal to the number 2 are 


reserved for future standardization. Numbers less than or equal to 0 are 
device dependent. 


String Class: Prompt and Echo Type 1 
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Position DataType Required Description 
1 Integer R Input buffer size in number of characters. 


2 Integer R Initial cursor position within the string. The 
initial position must follow the formula: 
1 <= initial_position <= (length_initial_string 
+1) 
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Stroke Class 


Stroke Class 


The GKS standard defines the following prompt and echo type values: 


Echo 
Type 


Number _ Description 


1 Display the stroke using implementation-defined techniques. The device 
can use any portion of the data record (for information specific to your 
device, refer to the DEC GKS Device Specifics Reference Manual.) 


2 Display a digital representation of the current stroke position within the 
echo area. 

3 Display a marker at each point of the current stroke. 

4 Display a line joining successive points of the current stroke. 


Prompt and echo type numbers greater than or equal to the number 5 are 
reserved for future standardization. Numbers less than or equal to 0 are 


device dependent. 


Stroke Class: Prompt and Echo Type 1 and 2 


Position DataType Required Description 


1 Integer R 
2 Integer N 
3 Real N 
4 Real N 
5 Real N 


Input buffer size in number of points. 
Editing position expressed as a stroke point. 
X world coordinate change vector. 

Y world coordinate change vector. 


Time interval, in seconds. 
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Stroke Class 


Stroke Class: Prompt and Echo Type 3 
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Position 


oar O ND & 


Data 
Type 
Integer 
Integer 
Real 
Real 
Real 
Integer 


Required Description 


2242442424350 


Input buffer size, in number of stroke points. 
Editing position expressed as a stroke point. 
X world coordinate change vector. 

Y world coordinate change vector. 

Time interval, in seconds. 


Attribute control flag. GKS$K_ACF_CURRENT 
(0) or GKS$K_ACF_SPECIFIED (1). Use the 
currently set output attributes or specify new 
attributes in this data record. 


If component 6 is GKS$K_ACF_SPECIFIED: 


Position 
7 


10 
11 
12 
13 
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Data 
Type 


Integer 
Integer 
Integer 


Integer 
Integer 
Real 

Integer 


Required Description 


N 


2 


22242 


Marker type aspect source flag. GKS$K_ASF_ 
BUNDLED (0) or GKS$K_ASF_INDIVIDUAL 
(1). 


Marker size scale factor aspect source flag. 
GKS$K_ASF_BUNDLED (0) or GKS$K_ASF_ 
INDIVIDUAL (1). 


Polymarker color index aspect source flag. 
GKS$K_ASF_BUNDLED (0) or GKS$K_ASF_ 
INDIVIDUAL (1). 


Polymarker index. 
Marker type index. 
Marker size scale factor. 


Polymarker color index. 
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Stroke Class: Prompt and Echo Type 4 


Position 


ao a fF WO NY FE 


Data 
Type 
Integer 
Integer 
Real 
Real 
Real 
Integer 


Required Description 


2242242450 


Input buffer size, in number of stroke points. 
Editing position expressed as a stroke point. 
X world coordinate change vector. 

Y world coordinate change vector. 

Time interval, in seconds. 


Attribute control flag. GKS$K_ACF_CURRENT 
(0) or GKS$K_ACF_SPECIFIED (1). Use the 
currently set output attributes or specify new 
attributes in this data record. 


If component 6 is GKS$K_ACF_SPECIFIED: 


Position 
7 


10 
11 
12 
13 


Data 
Type 


Integer 


Integer 


Integer 


Integer 
Integer 
Real 

Integer 


Required Description 


N 


Z 


2222 


Line type aspect source flag. GKS$K_ASF_ 
BUNDLED (0) or GKS$K_ASF_INDIVIDUAL 
(1). . 


Line width scale factor aspect source flag. 
GKS$K_ASF_BUNDLED (0) or GKS$K_ASF_ 
INDIVIDUAL (1). 


Polyline color index aspect source flag. 
GKS$K_ASF_BUNDLED (0) or GKS$K_ASF_ 
INDIVIDUAL (1 ). 


Polyline index. 
Line type index. 
Line width scale factor. 


Polyline color index. 


Input Functions 7-19 


Valuator Class 


Valuator Class 


The GKS standard defines the following prompt and echo type values: 


Echo 
Type 


Number Description 


1 Designate the current value using implementation-specific techniques. 
The device can use any portion of the data record (for information 
specific to your device, refer to the DEC GKS Device Specifics Reference 
Manual.) 


2 Display a graphical representation of the current value (such as a dial 
or pointer). 


3 Display a digital representation of the current value. 
Prompt and echo type numbers greater than or equal to the number 4 are 


reserved for future standardization. Numbers less than or equal to 0 are 
device dependent. 


Valuator Class: All Prompt and Echo Types 


Position DataType Required Description 


1 - Real R Low value of the numeric range. 
2 Real R High value of the numeric range. 
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7.2.1.1 


Using an Input Data Record 


Of the input data records described in the previous section, the DEC GKS 
supported graphics handlers must use all required components, but can 
use any number of the nonrequired components. Appendix J, DEC GKS 
Specific Input Values, describes the data records required by the DEC GKS 
supported handlers for each of the supported prompt and echo types, for 
each of the logical input devices. 


As shown in the previous section, the input data record components can be 
of several different data types. Most languages provide a way for you to 
declare a contiguous record that can contain items of different data types, 
but when using some languages, you need to use language-specific means to 
create such a construct. 


For tutorial information concerning the use of input data records, refer to 
the DEC GKS Reference Manual. For information concerning data record 
declarations, refer to the code examples in this chapter. 


7.3 Input Inquiries 


When using the DEC GKS input functions, you may need to inquire from 


the workstation description table, workstation state list, or both. If you 
require default values, inquire from the description table. If you require the 
currently set values, inquire from the state list. 


The following sections describe inquiry function programming technique. 


7.3.1 Default and Current Input Values 


If you do not want your application to set all the input values individually 
before calling one of the initializing functions (INITIALIZE LOCATOR, 


- INITIALIZE STROKE, and so forth), you can pass the input variables 


to one of two inquiry functions. To obtain default input values, you call 
the functions INQUIRE DEFAULT LOCATOR DEVICE DATA, INQUIRE 
DEFAULT STROKE DEVICE DATA, and so forth. To obtain the current 
input values, you call the functions INQUIRE LOCATOR DEVICE STATE, 
INQUIRE STROKE DEVICE STATE, and so forth. 


When calling those functions, you need to use caution when passing the data 
record buffer size to the inquiry functions. The buffer size is a modifiable 
variable (read/write), and when passed to the inquiry function, it must 
contain the size of the buffer in order for the inquiry function to properly 
return the contents of the data record. 
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After the function call, DEC GKS writes the amount of the buffer actually 
used. You can compare this value to the data record size to see if DEC 
GKS had to truncate the record when writing it to the buffer. If DEC GKS 
truncated the data record, you need to decide whether to continue execution 
or to alter the buffer size so that the entire record fits. 


For tutorial information concerning the use of input data records and 
their buffers, refer to the DEC GKS Reference Manual. For information 
concerning the lengths of data record buffers, Tefer to the code examples in 
this chapter. 


7.3.2 Device-Independent Programming 
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Depending on the type of input you use, you may need to call a large number 
of inquiry functions to create a device-independent program. For instance, 
you need to check the following information: 


_® The level of GKS, which determines the supported input operating 


modes. This information is important for applications that need to be 
transported to other systems. (DEC GKS is a level 2c implementation.) 


¢ The category of the workstation. 


¢ The number of input devices of a given class supported by the worksta- 
tion. 


¢ The prompt and echo types supported by a given workstation. 
¢ The maximum possible echo area available on a given workstation. 


¢ The data record information for a given workstation using a specified 
prompt and echo type (see Section 7.3.1 for detailed information). 


For information concerning device-independent programming technique, 


refer to the DEC GKS User Manual. All the code examples in this book are 


device independent. 


The following list presents the inquiry functions that you can use to obtain 
input information when writing device-independent code. 


INQUIRE CHOICE DEVICE STATE 

INQUIRE CURRENT NORMALIZATION TRANSFORMATION 
NUMBER 

INQUIRE DEFAULT CHOICE DEVICE DATA 

INQUIRE DEFAULT LOCATOR DEVICE DATA 

INQUIRE DEFAULT PICK DEVICE DATA 

INQUIRE DEFAULT STRING DEVICE DATA 

INQUIRE DEFAULT STROKE DEVICE DATA 
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INQUIRE DEFAULT VALUATOR DEVICE DATA 
INQUIRE DISPLAY SPACE SIZE 
INQUIRE INPUT QUEUE OVERFLOW 

INQUIRE LEVEL OF GKS 

INQUIRE LOCATOR DEVICE STATE 

INQUIRE NORMALIZATION TRANSFORMATION 
INQUIRE PICK DEVICE STATE 

INQUIRE SET OF OPEN WORKSTATIONS 
INQUIRE STRING DEVICE STATE 

INQUIRE STROKE DEVICE STATE 

INQUIRE VALUATOR DEVICE STATE 

INQUIRE WORKSTATION CATEGORY 

INQUIRE WORKSTATION TRANSFORMATION 


7.4 Overlapping Viewports 


This section assumes that you have a knowledge of the DEC GKS coordinate 
systems. You may want to review Chapter 6, Transformation Functions, 
before reading further. 


‘When defining normalization viewports, it is possible to cause them to 
overlap on the NDC plane. You must consider the effect this has during 
input requests. To illustrate the need for a viewport priority list for use 
during input, consider two normalization viewports: the default viewport 
({0,1] x [0,1]) of the unity transformation, and a viewport, belonging to 
normalization transformation number 1, having the range ([0.5, 1] x [0.5, 
1]) in NDC values. The viewport of normalization transformation number 1 
overlaps the right half of the default viewport. 


During stroke and locator input, the user positions the cursor on the device 
surface and returns one point or a series of points in device coordinates. 
DEC GKS translates the device coordinates to NDC points, and then uses 
the viewport input priority to determine which normalization transformation 
to use when translating the points to world coordinates. 


To decide which normalization viewport has a higher input priority, DEC 
GKS maintains a priority list. By default, DEC GKS assigns the highest 
priority to the unity transformation (0). The viewports of all remaining 
transformations decrease in priority as their transformation numbers 
increase (viewport 0 higher than viewport 1, 1 higher than 2, 2 higher than 
3, and so forth). 
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When using a locator class device, DEC GKS uses the normalization 
transformation of the highest input priority that contains the input point. 
When using stroke input, DEC GKS uses the normalization transformation 
of the highest priority that contains all the points in the stroke. Since a 
locator or stroke input device cannot return device coordinate points that 
can fall outside of the default normalization viewport ([0,1] x [0,1]), the 
unity transformation can always be used to transform stroke input data. 


For more information concerning transformations and viewport priority, 
refer to Chapter 6, Transformation Functions. 


7.5 Input Operating Modes 
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Using DEC GKS, you can use any of the logical input devices in any of the 
following three input operating modes: 


¢ Request mode 
¢ Sample mode 
¢ Event mode 


If you need to have the application program work synchronously with the 
input process (if the application must pause to wait for input to be complete), 
then you can use request mode. Request mode is the only input mode that 
you can use without first calling one of the SET class MODE functions. 


If you need to have the application program work asynchronously with the 
input process (if the application must run while the user enters input), then 
you can use sample or event mode. Sample and event mode differ. Using 
sample mode, the application takes the current measure of an input device 
without the user having to trigger. While in event mode, the device handler 
places triggered input values in a time-ordered queue to be accessed when 
the application chooses. 


To change the input operating mode for a given device, you call one of the 
functions SET LOCATOR MODE, SET STROKE MODE, and so forth. These 
functions serve the second purpose of enabling and disabling echoing of the 
input prompt. This feature is useful when the DEC GKS echo types are 
inadequate and you need to echo the input in an application-specific manner. 


By default, all device prompts are active at once. For instance, if you press 
the arrow keys, you alter all prompts on the workstation surface whose 
devices use the arrow keys. Device handlers can provide methods for the 
user to deactivate all prompts except one, for each logical input device. In 
this way, the user can cycle through the devices, changing only one measure 
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at a time, in some device-specific order. For more information on cycling 
logical input devices, refer to Appendix J, DEC GKS Specific Input Values. 


NOTE 


You cannot cycle past a device whose echoing is disabled. 
(Normally, notification of the device’s turn in the cycle is the 
displaying of the device’s prompt.) Using the corresponding 
physical device will always alter the measure of a nonechoing 
device. For instance, if you use pick device 1 on the VT241 while 
disabling its echoing, pressing the arrow keys always changes 
the measure of this device no matter how you cycle through the 
remaining prompting devices. 


The following sections describe each of the input operating modes in greater 
detail. 


7.5.1 Request Mode 


In request mode, the application program pauses, and DEC GKS waits for 
the user either to trigger the end of input or to perform a break. You can 
use a logical input device in request mode without calling SET LOCATOR 
MODE, SET STROKE MODE, and so forth, as long as you have not 
previously set the device to some other mode (request mode is the DEC GKS 
default mode). 


In order to initialize a logical input device, you must make sure that the 
device’s prompt does not currently appear on the workstation surface. To 
initialize a device, the device must be in request mode. 


You can place any or all the supported logical input devices in request 
mode at any one time, but you can only request input from one device at a 
time. You request input, from a specified logical input device on a specified 
workstation, by calling one of the functions REQUEST CHOICE, REQUEST 
LOCATOR, REQUEST PICK, REQUEST STRING, REQUEST STROKE, 
or REQUEST VALUATOR. Once you request input by calling one of the 
REQUEST class functions, the input prompt appears on the workstation 
surface (if echoing is enabled). 


In request mode, there are several ways to trigger or break a request for 
input. If the user triggers the logical input device (as described in Appendix 
J, DEC GKS Specific Input Values), DEC GKS writes the value 
GKS$K_STATUS_OK to the request function input_status argument. If 
the user performs a break during the request for input, which may be 
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a different action on different workstations, DEC GKS writes the value 
GKS$K_STATUS_NONE to the request function input_status argument. 


Choice and pick logical input devices allow the user an option other than 
returning data or breaking input. These logical devices allow the user to end 
the input process without choosing or picking. If the user triggers the input 
device without moving the prompt, DEC GKS returns one of the appropriate 
values, GKS$K_STATUS_NOCHOICE or GKS$K_STATUS_NOPICK, to the 
input_status argument. (DEC GKS also returns GKS$K_STATUS_NOPICK 
if the user is not currently positioning the aperture on a segment.) 


Example 7-1 illustrates the use of the locator logical input device in request 
mode. Following the program example, Figure 7-2 illustrates the program’s 
effect on a VT241 workstation. 


Example 7-1: Using a Locator Logical Input Device in Request Mode 


Cc This program initializes and requests locator input from a VT241. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
+] INTEGER WS_ID, DATA_RECORD( 1 ), PROMPT_ECHO TYPE, 
* ERROR STATUS, INPUT_MODE, ECHO FLAG, XFORM, 
* RECORD_BUFFER_LENGTH, RECORD SIZE, INPUT_STATUS, 


* DEVICE NUM : 
REAL ECHO AREA( 4 ), WORLD _X, WORLD Y 
DATA WS_ID / 1 /, DEVICE_NUM / 1 /, RECORD _BUFFER_LENGTH / 4 / 


CALL GKSSOPEN_GKS( ‘SYS$ERROR:’ ) 
CALL GKS$OPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


13) CALL GKS$INQ_LOCATOR_STATE( WS_ID, DEVICE_NUM, 
GKS$K_VALUE_REALIZED, ERROR STATUS, INPUT MODE, 
ECHO FLAG, XFORM, WORLD_X, WORLD _Y, 
PROMPT_ECHO TYPE, ECHO_AREA, DATA_RECORD, 
RECORD BUFFER_LENGTH, RECORD SIZE ) 


* + Fe 


4) PROMPT ECHO TYPE = 1 


Cc Since the device is in request mode by default, initialize the device. 


8 CALL GKS$INIT_LOCATOR( WS_ID, DEVICE_NUM, WORLD_X, 
* WORLD_Y, XFORM, PROMPT ECHO TYPE, ECHO AREA, 
* DATA_RECORD,. RECORD _BUFFER_LENGTH ) 


6) CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT MODE REQUEST, GKS$K_ECHO ) 


7] CALL GKSS$REQUEST_LOCATOR( WS_ID, DEVICE_NUM, INPUT_STATUS, 
* XFORM, WORLD_X, WORLD Y ) 


(continued on next page) 


7-26 Input Functions 


Example 7-1 (Cont.): Using a Locator Logical Input Device in Request 


Mode 


Output the input locator position, in world coordinates. 
WRITE (6,*) WORLD_X, WORLD_Y 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example. 


The DEC GKS VT241 handler ignores the data record for all supported 
locator prompt and echo types. This is a dummy argument. 


The echo area variable is an array of real numbers representing the 
rectangular echo area, in device coordinates. The echo area defines a 
portion of the workstation surface on which the prompt moves. 


The function INQUIRE LOCATOR DEVICE STATE initializes the 
variables you need to pass to the input functions. The constant GKS$K_ 
VALUE_REALIZED tells the graphics handler to return the input values 
as they are implemented, instead of the way that the application may 
have set the values (GKS$K_VALUE_SET). 


After the function call, record_buffer_length contains the amount of the 
buffer filled with the written data record. If record_size is larger than 
record_buffer_length, then you know that the data record was truncated 
to fit into your declared buffer. 


@ This code assigns new values to the input variables. For instance, the 


prompt and echo type is set to the number 1. 


The function INITIALIZE LOCATOR initializes the locator logical input 
device. 


The function SET LOCATOR MODE sets the input operating mode to 
request and enables echo. Request input and enabled echo are the DEC 
GKS defaults. 


The function REQUEST LOCATOR causes the device handler to place 
the input prompt on the workstation surface. At this point in the 
application, the input process takes control and the user can enter 
input. The device handler writes the world coordinate values, and the 
normalization transformation number used to translate the points, to 
the last arguments. 
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Figure 7—2 shows the screen of a VT241 terminal at the request for input. 


Figure 7-2: Initializing the Locator Logical input Device—VT241 
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7.5.2 Sample Mode 
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In sample mode, the application program and the input process operate 
asynchronously. The user changes the input measure, and when the 
application chooses, it samples (takes) the current measure of the logical 
input device. The application determines when to end the input session. 


As soon as you specify sample mode to one of the functions, SET LOCATOR 
MODE, SET STROKE MODE, and so forth, the input prompt appears on 
the workstation surface (if echoing is enabled). At this point, the user can 
enter input, but cannot trigger the device or cancel input. 


After you place the device in sample mode, you cannot reinitialize the device 
(by calling one of the INITIALIZE class functions) until you remove the 
device’s prompt from the workstation surface. To do this, place the device 
in request mode, reinitialize the device, and then place the device back into 
sample mode. 
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If you choose, you can place any or all the supported logical input devices 
into sample mode at one time, but you only sample from one device at 

a time. At any point in the application, the program can call one of the 
functions SAMPLE LOCATOR, SAMPLE STROKE, and so forth, and the 
device handler returns the current measure from the specified workstation 
and the specified logical input device. When the program reaches some 
application-defined condition, the application can remove the input prompt 
from the workstation surface by changing the input mode from sample mode 
back to request mode. 


When sampling choice and pick logical input devices, you can obtain an 
additional input status called GKS$K_STATUS_NOCHOICE (if the user did 
not alter the device’s measure since it had been activated) or 
GKS$K_STATUS_NOPICK (if the user did not move the aperture, or if 

the user is not currently positioning the aperture on a segment). Under 
the specified conditions, DEC GKS writes these values to the input_status 
argument. 


Example 7-2 illustrates the use of the locator logical input device in sample 
mode. Following the program example, Figures 7—3 through 7—5 illustrate 
the program’s effect on a VT241 workstation. 


Example 7-2: Using a Locator Logical Input Device in Sample Mode 


Cc This program initializes and samples locator input from a VT24l1. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
1 ] INTEGER WS_ID, DATA_RECORD( 1 ), PROMPT _ECHO TYPE, 
* ERROR STATUS, INPUT_MODE, ECHO FLAG, XFORM, 
* RECORD BUFFER LENGTH, RECORD SIZE, INPUT STATUS, 
* DEVICE NUM 


2) REAL ECHO_AREA( 4 ), WORLD _X, WORLD_Y, LARGER 
DATA WS_ID / 1 /, DEVICE_NUM / 1 /, LARGER / 0.03 / 


CALL GKS$OPEN_GKS( ’SYS$ERROR:’ ) 

CALL GKS$OPEN WS( WS_ID, GKS$K_CONID DEFAULT, 
* GKSSK_VT240 ) 

CALL GKS$ACTIVATE_WS( WS_ID ) 


C3 CALL GKS$INQ_LOCATOR_STATE( WS_ID, DEVICE_NUM, 
* GKS$K_VALUE REALIZED, ERROR_STATUS, INPUT_MODE, 
* ECHO FLAG, XFORM, WORLD _X, WORLD_Y, 
* PROMPT ECHO TYPE, ECHO AREA, DATA_RECORD, 
* RECORD BUFFER_LENGTH, RECORD SIZE ) 


(continued on next page) 
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Example 7-2 (Cont.): Using a Locator Logical Input Device in Sample 





Mode | 
Cc Set the initial position of the cursor. 
WORLD _X = 0.9 
WORLD _Y = 0.0 
Cc To initialize a device, make sure it’s in request mode (the DEC 


Cc GKS default). 
CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE REQUEST, GKS$K_ECHO ) 


4) CALL GKS$INIT_LOCATOR( WS_ID, DEVICE_NUM, WORLD X, 
* WORLD_Y, XFORM, PROMPT ECHO TYPE, ECHO AREA, 
* DATA RECORD, RECORD BUFFER_LENGTH ) 


6 CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT MODE SAMPLE, GKSS$K_ECHO ) 


Cc Instruct the user. 
CALL GKS$SET_TEXT_HEIGHT( LARGER ) 
CALL GKSSTEXT( 0.05, 0.95, ‘Move the locator upwards.’ ) 
CALL GKSSTEXT( 0.05, 0.90, ’I will say when to stop.’) 


Cc Do until the user moves the cursor closest to the top of the 
Cc device surface. 
DO WHILE ( WORLD_Y .LT. 0.9 ) 


6) CALL GKS$SAMPLE_LOCATOR( WS_ID, DEVICE_NUM, 
* XFORM, WORLD_X, WORLD Y ) 
Cc Tease the user as the prompt gets closer. 
IF ( ( WORLD Y .GT. 0.1 ) .AND. 
* ( WORLD _Y .LT. 0.5 ) ) THEN 
CALL GKSS$TEXT( 0.05, 0.85, ‘’You are still far away.’) 
ENDIF 
IF ( ( WORLD _Y .GT. 0.5 ) .AND. 
* ( WORLD _Y .LT. 0.7 ) ) THEN 
CALL GKSSTEXT( 0.05, 0.80, ’You are getting closer.’) 
ENDIF 
IF ( ( WORLD Y .GT. 0.7 ) .AND. 
* ( WORLD _Y .LT. 0.9 ) ) THEN 
CALL GKSSTEXT( 0.05, 0.75, ‘You are REALLY close.’) 
ENDIF 
ENDDO 


CALL GKSSTEXT( 0.05, 0.70, ‘YOU MADE IT!!!’) 


Cc Turn off the sample prompt. 


7] CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_REQUEST, GKS$K_ECHO ) 


(continued on next page) 
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Example 7-2 (Cont.): Using a Locator Logical Input Device in Sample 


Mode 


CALL GKSSDEACTIVATE WS( WS_ID ) 
CALL GKSSCLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


The DEC GKS VT241 handler ignores the data record for all supported 
locator prompt and echo types. This is a dummy argument. 


The echo area variable is an array of real numbers representing the 
rectangular echo area in device coordinates. The echo area defines a 
portion of the workstation surface on which the prompt moves. 


The function INQUIRE LOCATOR STATE initializes the variables 

you need to pass to the input functions. The constant 
GKS$K_VALUE_REALIZED tells the graphics handler to return the 
input values as they are implemented, instead of the way that the 
application may have set the values (GKS$K_VALUE_SET). 

After the function call, record_buffer_length contains the amount of the 
buffer filled with the written data record. If record_size is larger than 
record_buffer_length, then you know that the data record was truncated 
to fit into your declared buffer. 

The function INITIALIZE LOCATOR initializes the locator logical input 
device. 


© The function SET LOCATOR MODE sets the input operating mode to 


sample and enables echo. 


In the loop, the call to SAMPLE LOCATOR writes the current measure 
of the device to its arguments until the user moves the cursor close 

to the top of the workstation surface. Note that when using a VT241 
locator device number 1, the user moves the cursor using the arrow 
keys. Pressing RETURN has no effect in sample mode; the application 
has complete control in accepting a sample input value. 


When sampling is complete, the call to SET LOCATOR MODE sets the 
input operating mode to request mode, removes the prompt from the 
workstation surface, and ends the sample input session. 
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Figures 7-3 through 7-5 show the screen of a VT241 terminal as the user 
moves the cursor towards the top of the workstation surface. Notice that 
triggering the device does not affect the acceptance of input. 


Figure 7-3: The Locator Logical Input Device in Sample Mode—VT241 


Move the locator upwards, 
I will say when to stop. 
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Figure 7-4: The Locator Logical Input Device in Sample Mode—VT241 


Move the locator upwards, 
I will say when to stop, 
You are still far away, 

You are getting closer, 
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Figure 7-5: The Locator Logical Input Device in Sample Mode—VT241 


Move the locator upwards, 

I will say when to stop, + 
You are still far away, 

You are getting closer. 


You are REALLY close, 
YOU MADE IT!!! 
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7.5.3 Event Mode 
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In event mode, the application program and the input process operate 
asynchronously. Event mode differs from sample mode in that the user must 
trigger input values that DEC GKS then places in a time-ordered queue. 
Each set of input values is a report. The application chooses when to remove 
the reports from the queue, beginning with the first input value entered by 
the user. 


As soon as you specify event mode to one of the functions SET LOCATOR 
MODE, SET STROKE MODE, and so forth, the input prompt appears on 
the workstation surface (if echoing is enabled). At this point, the user can 
generate events that the device handler places in the event input queue. 


After you place the device in event mode, you cannot reinitialize the device 
(by calling one of the INITIALIZE class functions) until you remove the 
device’s prompt from the workstation surface. To do this, place the device 
in request mode, reinitialize the device, and then place the device back into 
event mode. 
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If desired, the application programmer can process reports generated by 

the user. To remove reports from the event input queue, call the function 
AWAIT EVENT. AWAIT EVENT checks the event queue, for a length of time 
up to the amount specified by the timeout argument. If the event queue 
contains at least one report, then AWAIT EVENT removes the oldest report, 
places it in the current event report entry in the DEC GKS state list, and 
allows the application to resume. If the queue remains empty for the entire 
timeout period, AWAIT EVENT writes GKS$K_INPUT_CLASS_NONE to its 
input_class argument and allows the application to resume. 


Each input report contains the following information that corresponds to the 
generated event: 


¢ The workstation identifier 
¢ The input class of the device 
¢ The logical input device number 


To process the information in the current event report, you need to check 
the value written to the input_class argument of AWAIT EVENT. Once you 
determine the class of the device that generated the event, you call one of 
the functions GET LOCATOR, GET STROKE, and so forth. 


Remember that repeated calls to one of the functions, GET LOCATOR, 
GET STROKE, and so forth, will write the same values to the output 
arguments since these funtions always obtain information from the current 
event report. The current event report does not change unless you call 
AWAIT EVENT to fetch another report from the queue. Once you do this, a 
subsequent call to one of the GET class functions obtains new input values. 


If you decide that you have enough information from a particular logical 
input device, you can place the device back in request mode (stopping 

the generation of further events), and you can then flush all the events 
generated by that device that remain in the event input queue. To flush 
reports generated by a logical input device from the event input queue, call 
the function FLUSH DEVICE EVENTS. 


The following sections present the following information: 


e A program example using event mode 


e The handling of simultaneously generated events (INQUIRE MORE 
SIMULTANEOUS EVENTS) 


¢ The handling of input queue overflow (INQUIRE INPUT QUEUE 
OVERFLOW) 
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Program Example Using Event Mode 


Example 7-3 illustrates the use of the locator logical input device in event 
mode. Following the program example, Figures 7-6 through 7-8 illustrate 
the program’s effect on a VT241 workstation. 


Example 7-3: Using a Locator Logical Input Device in Event Mode 


This program initializes and generates locator events from a VT241. 
IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, DATA_RECORD( 1 ), PROMPT_ECHO TYPE, 

* ERROR_STATUS, INPUT MODE, ECHO FLAG, XFORM, 

* RECORD BUFFER_LENGTH, RECORD_SIZE, INPUT_STATUS, 

* DEVICE _NUM, CLASS 


REAL ECHO ARBA( 4 ), WORLD _X, WORLD_Y, LARGER 
DATA WS_ID / 1 /, DEVICE_NUM / 1 /, LARGER / 0.03 / 


CALL GKS$OPEN_GKS( 'SYS$ERROR:’ ) 

CALL GKS$OPEN WS( WS_ID, GKS$K_CONID_DEFAULT, 
* GKS$K_VT240 ) 

CALL GKS$ACTIVATE_WS( WS_ID ) 


Obtain the current locator input values. 


CALL GKSS$INQ_LOCATOR_STATE( WS_ID, DEVICE_NUM, 
GKS$K_VALUE_REALIZED, ERROR_STATUS, INPUT_MODE, 
ECHO_FLAG, XFORM, WORLD X, WORLD Y, 

PROMPT _ECHO_TYPE, ECHO_AREA, DATA_RECORD, 
RECORD BUFFER_LENGTH, RECORD SIZE ) 


e+ + He 


Set the initial position of the cursor. 
WORLD_X = 0.9 
WORLD _Y = 0.0 


To initialize a device, make sure it’s in request mode (the DEC 
GKS default). 

CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 

* GKSS$K_INPUT_MODE_ REQUEST, GKS$K_ECHO ) 


CALL GKS$INIT_LOCATOR( WS_ID, DEVICE_NUM, WORLD_X, 
* WORLD_Y, XFORM, PROMPT _ECHO_TYPE, ECHO AREA, 
* DATA_RECORD, RECORD _BUFFER_LENGTH ) 


CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT MODE EVENT, GKS$K_ECHO ) 


Inform the user. 

CALL GKSSSET_ TEXT HEIGHT ( LARGER ) 

CALL GKSSTEXT( 0.05, 0.95, ’Move the locator upwards.’ ) 
CALL GKSSTEXT( 0.05, 0.90, ‘Trigger until I say to stop.’) 





(continued on next page) 
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Example 7-3 (Cont.): Using a Locator Logical Input Device in Event 
Mode 





Cc Do until the user moves the cursor closest to the top of the 
Cc device surface. 
DO WHILE ( WORLD_Y .LT. 0.9 ) 


Cc Check the event queue. 
CALL GKS$AWAIT_EVENT( 0.0, WS_ID, CLASS, DEVICE_NUM ) 
IF ( CLASS .NE. GKS$K_INPUT_CLASS_NONE ) THEN 
CALL GKS$GET_LOCATOR( XFORM, WORLD_X, WORLD_Y ) 
ENDIF 
Cc Tease the user as the prompt gets closer. 
IF ( ( WORLD_Y .GT. 0.1 ) .AND. 
* ( WORLD _Y .LT. 0.5 ) ) THEN 
CALL GKSSTEXT( 0.05, 0.85, ‘You are still far away.’) 
ENDIF 
IF ( ( WORLD_Y .GT. 0.5 ) .AND. 
* ( WORLD_Y .LT. 0.7 ) ) THEN 
CALL GKSS$TEXT( 0.05, 0.80, ‘You are getting closer.’) 
ENDIF 
IF ( ( WORLD _Y .GT. 0.7 ) .AND. 
* ( WORLD_Y .LT. 0.9 ) ) THEN 
CALL GKSSTEXT( 0.05, 0.75, ‘You are REALLY close.’) 
ENDIF 
ENDDO 
CALL GKSSTEXT( 0.05, 0.70, ‘YOU MADE IT!!!’) 
Cc Turn off the event prompt. 
CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 


* GKS$K_INPUT_MODE REQUEST, GKS$K_ECHO ) 


CALL GKSSDEACTIVATE WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ The DEC GKS VT241 handler ignores the data record for all supported 
locator prompt and echo types. This is a dummy argument. 


@ The echo area variable is an array of real numbers representing the 
rectangular echo area, in device coordinates. The echo area defines a 
portion of the workstation surface on which the prompt moves. 
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© The function INQUIRE LOCATOR STATE initializes the 
variables you need to pass to the input functions. The constant 
GKS$K_VALUE_REALIZED tells the graphics handler to pass the input 
values as they are implemented, instead of the way that the application 
may have set the values (GKS$K_VALUE_SET). 


After the function call, record_buffer_length contains the amount of the 
buffer filled with the written data record. If record_size is larger than 
record_buffer_length, then you know that the data record was truncated 
to fit into your declared buffer. 


© The function INITIALIZE LOCATOR initializes the locator logical input 
device. 


© The function SET LOCATOR MODE sets the input operating mode to 
event and enables echo. 


© In the loop, the call to AWAIT EVENT immediately checks the input 
queue (as specified by the timeout argument of 0). If the user has not yet 
entered an event, or if the application has removed all reports generated 
thus far, AWAIT EVENT returns GKS$K_INPUT_CLASS_NONE to its 
input_class argument. 


@ As long as the input_class argument is not GKS$K_INPUT_CLASS_ 
NONE, you can call GET LOCATOR, since that is the only other device 
class that can generate an event. 


© When accepting event reports is complete, the call to SET LOCATOR 
MODE sets the input operating mode to request mode, removes the 
prompt from the workstation surface, and ends the event input session. 


Figure 7-6 illustrates the surface of the VT241 when the input mode is set. 
Figure 7—7 illustrates the surface of the VIT241 when the user moves the 
cursor but does not trigger the device. Figure 7-8 illustrates the surface of 
the VT241 when the user triggers an event. 
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Figure 7-6: The Locator Logical Input Device in Event Mode—VT241 


Move the locator upwards, 
Trigger until I say to stop. 
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Figure 7-7: The Locator Logical Input Device in Event Mode—VT241 


Move the locator upwards, 
Trigger until I say to stop. + 
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Figure 7-8: The Locator Logical Input Device in Event Mode—VT241 


Move the locator upwards. 
Trigger until I say to stop, —+- 


YOU MADE IT!!! — 
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7.5.3.2 Placing Multiple Devices into Event Mode 
This section describes the following: 
¢ Methods by which you place more than one logical input device into 
event mode. : . 
e How to handle simultaneous events. 
e An example of cycling through devices currently in event mode. 


Example 7-4 places both a pick and valuator logical input device into event 
mode, and handles simultaneously generated events. This example places 
two diagonally split boxes on the workstation’s surface and defines them as 
separate segments. (This example is a portion of Example 7—7.) Using pick 
input to choose the appropriate box and valuator input to determine the 
amount of scaling, the user can generate events to increase or decrease the 
size of each box. Input ends when the user picks the triangle labeled STOP. 
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Following the program example, Figures 7-9 through 7~12 illustrate the 


effects of this program on a VT241. 


Example 7-4: Placing Two Devices into Event Mode 





c This program generates events from two devices on a VT241. 

IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, INITIAL STATUS, SEGMENT, 

* PICK_ID, PROMPT ECHO TYPE, ERROR_STATUS, 

* INPUT MODE, ECHO FLAG, RECORD BUFFER_LENGTH, 

* RECORD_SIZE, PICK_INPUT_STATUS, DEVICE_NUM, BOX_1, BOX_2, 

* TRIANGLE 1, TRIANGLE 2, NUM POINTS, CLASS 


tt] REAL ECHO AREA( 4 ), PICK DATA RECORD( 1 ), 
* VAL DATA RECORD( 2 ) 
REAL X_VALUES( 4 ), Y_VALUES( 4 ), LARGER, 


* XFORM MATRIX1( 6 ), XFORM MATRIX2( 6 ), VALUE, 
* UPPER_LIMIT, LOWER LIMIT 

DATA WS_ID / 1 /, DEVICE_NUM / 1 /, BOX 1/1 /, 
* BOX_2 / 2 /, TRIANGLE_1 / 1 /, TRIANGLE _2 / 2 /, 
* NUM POINTS / 4 /, LARGER / 0.03 / 

DATA X_VALUES / 0.1, 0.4, 0.1, 0.1 / 

DATA Y_VALUES / 0.3, 0.6, 0.6, 0.3 / 


Cc The two elements in the valuator data record are the upper 
Cc and lower limits. 
EQUIVALENCE ( VAL _DATA_RECORD( 1 ), LOWER_LIMIT ) 
EQUIVALENCE ( VAL_DATA_RECORD( 2 ), UPPER_LIMIT ) 


CALL GKSS$OPEN_GKS( ’SYS$ERROR:’ ) 
CALL GKSSOPEN WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKSS$ACTIVATE_WS( WS_ID ) 


CALL GKS$SET_FILL_INT STYLE( GKS$K_INTSTYLE_SOLID ) 


© CALL GKS$CREATE_SEG( BOX_1 ) 

CALL GKS$SET_PICK_ID( TRIANGLE_1 ) 

CALL GKS$SET_FILL_COLOR_INDEX( 2 ) 

CALL GKS$FILL_AREA( NUM POINTS, X_VALUES, Y_VALUES ) 
X_VALUES( 3 ) = 0.4 

Y_VALUES( 3) = 0.3 

CALL GKS$SET_PICK_ID( TRIANGLE 2 ) 

CALL GKS$SET FILL COLOR_INDEX( 3 ) 

CALL GKS$FILL_AREA( NUM POINTS, X_VALUES, Y_VALUES ) 
CALL GKS$CLOSE_SEG() 


(continued on next page) 
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* 
* 
* 
* 


X_VALUES( 1 ) = 0.6 
X_VALUES( 2 ) = 0.9 
X_VALUES( 3 ) = 0.6 
X_VALUES( 4 ) = 0.6 
Y_VALUES( 3 ) = 0.6 


CALL GKS$SET_PICK_ID( TRIANGLE_1 ) 


CALL GKS$CREATE_SEG( BOX 2 ) 

CALL GKSS$SET_ FILL COLOR_INDEX( 2 ) 

CALL GKS$FILL_AREA( NUM POINTS, X_VALUES, Y_VALUES ) 
X_VALUES( 3 ) = 0.9 

Y_VALUES( 3 ) = 0.3 

CALL GKS$SET_PICK_ID( TRIANGLE 2 ) 

CALL GKS$SET FILL COLOR_INDEX( 3 ) 

CALL GKS$FILL AREA( NUM POINTS, X_VALUES, Y VALUES ) 
CALL GKS$CLOSE_SEG() 


CALL GKS$SET_SEG DETECTABILITY ( BOX_1, GKS$K_DETECTABLE ) 
CALL GKS$SET_SEG DETECTABILITY ( BOX _2, GKS$K_DETECTABLE ) 


CALL GKS$SET_TEXT _HEIGHT( LARGER ) 
CALL GKSS$TEXT( 0.2, 0.45, ‘1’) 
CALL GKSS$TEXT( 0.3, 0.45, '2’) 
CALL GKSS$TEXT( 0.7, 0.45, ‘17) 
CALL GKSS$TEXT( 0.8, 0.45, ‘’STOP’) 


Declare a data length of one long word which will hold the 
size of the pick prompt. 

RECORD_BUFFER_LENGTH = 4 

CALL GKS$INQ PICK_STATE ( WS_ID, DEVICE NUM, 
GKS$K_VALUE_REALIZED, ERROR_STATUS, INPUT_MODE, 

ECHO FLAG, INITIAL STATUS, SEGMENT, PICK_ID, 

PROMPT ECHO TYPE, ECHO AREA, PICK_DATA_ RECORD, 

RECORD _BUFFER_LENGTH, RECORD SIZE ) 


SEGMENT = BOX_1 
PICK_ID = TRIANGLE 1 
INITIAL STATUS = GKSSK_STATUS NOPICK 


(continued on next page) 
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Cc Initialize the segment transformation matrixes to the unity 
Cc transformation. 

CALL GKS$EVAL | XFORM _MATRIX( 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 

* 1.0, GKSSK_ COORDINATES WC, XFORM_MATRIX1 ) 

CALL GKS$EVAL_XFORM MATRIX ( 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 

* 1.0, GKS$K_COORDINATES WC, XFORM_MATRIX2 ) 


To initialize a device, make sure it’s in request mode (the DEC 
GKS default). 

CALL GKS$SET_PICK_MODE( WS_ID, DEVICE_NUM, 

* GKSS$K_ INPUT _| MODE_REQUEST, ~ GKS$K_ -ECHO ) 


aa 


CALL GKS$INIT_PICK( WS_ID, DEVICE_NUM, INITIAL_STATUS, 
* SEGMENT, PICK_ID, PROMPT ECHO TYPE, ECHO_AREA, 
* PICK_DATA_RECORD, RECORD _BUFFER_LENGTH ) 


Cc Set the input operating mode to event. 
CALL GKS$SET_PICK_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_EVENT, GKS$K_ECHO ). 


Cc Reinitialize the input values for the valuator device. 


5] RECORD _BUFFER_LENGTH = 8 
CALL GKS$INQ_VALUATOR_STATE( WS_ID, DEVICE_NUM, 
* ERROR_STATUS, INPUT MODE, ECHO FLAG, VALUE, 
* PROMPT ECHO TYPE, ECHO_AREA, VAL _DATA_RECORD, 
7 RECORD _ BUFFER_LENGTH, RECORD SIZE ) 


VALUE = 1.0 
UPPER_LIMIT 
LOWER_LIMIT 


1.5 
0.5 


CALL GKS$INIT_VALUATOR( WS_ID, DEVICE_NUM, 
* VALUE, PROMPT ECHO TYPE, ECHO_AREA, 
* VAL_DATA_RECORD, RECORD _BUFFER_LENGTH 


CALL GKS$SET_VALUATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_EVENT, GKS$K_ECHO ) 





(continued on next page) 
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Cc Tell the user the task. 

CALL GKSSTEXT( 0.05, 0.95, 

* ‘Move the cursor to scale a box.’ ) 
CALL GKSSTEXT( 0.05, 0.90, 

* 'PF1l cycles input devices.’) 

CALL GKSSTEXT( 0.05, 0.85, 

* 'PF2 activates all devices.’) 

CALL GKSSTEXT( 0.05, 0.80, 

* ‘To finish, pick STOP.’ ) 


Cc Initialize variables. 
PICK_INPUT_STATUS = GKS$K_STATUS_NOPICK 


Cc Do until the user picks the second triangle in the second box. 
DO WHILE (( SEGMENT .NE. 2) .OR. ( PICK_ID .NE. 2 )) 


Cc Check the event queue. 
CALL GKSS$AWAIT_EVENT( 0.0, WS_ID, CLASS, DEVICE_NUM ) 


Cc Check for queue overflow. 
CALL GKS$INQ_INPUT_QUEUE_OVERFLOW( ERROR_STATUS, WS_ID, 
* CLASS, DEVICE_NUM ) 


Cc If the queue has overflowed... 
IF ( ERROR_STATUS .EQ. 0 ) THEN 
CALL OVERFLOW( WS_ID, CLASS, DEVICE_NUM, PICK_INPUT_STATUS, 
* SEGMENT, PICK_ID, XFORM_MATRIX1, XFORM_MATRIX2 ) 
ENDIF 


CALL SCALE_IT( WS_ID, CLASS, DEVICE_NUM, PICK_INPUT_STATUS, 
* SEGMENT, PICK_ID, XFORM MATRIX1, XFORM_MATRIX2 ) 


ENDDO 


Cc Turn off the event prompts. 
CALL GKS$SET_PICK_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_ REQUEST, GKS$K_ECHO ) 
CALL GKS$SET_VALUATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_ REQUEST, GKS$K_ECHO ) 


CALL GKS$DEACTIVATE_WS( WS _ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS() 

END 


(continued on next page) 
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Cc KKKKKKKKK KKK KEK KKK KKK KKK KREK KK KKK RK KKK KK KKKKEKKRKKKKKKEKKKKKEKKKKKEKK 


Cc Scale the appropriate segment... 
SUBROUTINE SCALE_IT( WS_ID, CLASS, DEVICE_NUM, 
* PICK_INPUT_STATUS, SEGMENT, PICK_ID, XFORM MATRIX], 
* XFORM MATRIX2 ) 


IMPLICIT NONE 
INCLUDE ' SYS$LIBRARY:GKSDEFS. FOR’ 

13) INCLUDE ’SYSS$LIBRARY :GKSMSGS . FOR’ 
INTEGER CLASS, PICK_INPUT_STATUS, WS_ID, DEVICE_NUM, 
* PICK ID, SEGMENT, MORE EVENTS, ERROR_STATUS 
REAL VALUE, XFORM MATRIX1( 6 ), XFORM MATRIX2( 6 ), FIXED_X, 
* FIXED Y, TEMP X( 1), TEMP Y( 1 ) 


Cc Get all the simultaneous event reports. 
MORE_EVENTS = GKS$K_MORE_ EVENTS 


© DO WHILE ( MORE EVENTS .NE. GKS$K_NOMORE EVENTS ) 


IF ( CLASS .EQ. GKS$K_INPUT_CLASS VALUATOR ) THEN 
CALL GKS$GET_VALUATOR( VALUE ) 

ELSE IF ( CLASS .EQ. GKS$K_INPUT CLASS PICK ) THEN 
CALL GKS$GET_PICK( PICK_INPUT STATUS, SEGMENT, 

* PICK_ID ) 

ENDIF 


Cc Set the flag MORE EVENTS... 
CALL GKSS$INQ_ MORE _SIMUL_EVENTS( ERROR_STATUS, 
* MORE EVENTS ) 


Cc If there are more simultaneous events, take them from the queue... 
IF ( MORE_EVENTS .EQ. GKS$K_MORE_ EVENTS) THEN 
CALL GKSSAWAIT_EVENT( 0.0, WS_ID, CLASS, DEVICE_NUM ) 


ENDIF 
ENDDO 
Cc If appropriate, scale the segment. 
© IF ((( PICK_INPUT_STATUS .NE. GKSSK_STATUS_NOPICK ) .AND. 
* ( VALUE .NE. 1.0 )) .AND. 
* ( CLASS .NE. GKSSK_INPUT_CLASS NONE )) THEN 





(continued on next page) 
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Cc Scale the appropriate segment... 
IF ( SEGMENT .EQ. 1 ) THEN 
FIXED X = 0.25 
FIXED Y = 0.45 
CALL GKS$ACCUM_XFORM MATRIX( XFORM_MATRIX1, 
* FIXED X, FIXED _Y, 0.0, 0.0, 0.0, VALUE, 
* VALUE, GKS$K_COORDINATES WC, XFORM MATRIX1 ) 
CALL GKS$SET_SEG XFORM( SEGMENT, XFORM_MATRIX1 ) 
ELSE 
FIXED X = 0.75 
FIXED_Y = 0.45 
CALL GKSS$ACCUM_XFORM MATRIX( XFORM_ MATRIX2, 
* FIXED X, FIXED_Y, 0.0, 0.0, 0.0, VALUE, 
* VALUE, GKS$K_COORDINATES WC, XFORM MATRIX2 ) 
CALL GKSS$SET_SEG XFORM( SEGMENT, XFORM MATRIX2 ) 
ENDIF 


CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM_FLAG ) 
ENDIF 
END 


The following numbers correspond to the numbers in the previous example: 


@ This application must define the two data records— pick_data_record and 
val_data_record. The pick_data_record contains a single real value that 
is the size of the pick aperture in device coordinates, as required by the 
VT241 graphics handler. The val_data_record contains two real values 
that are the upper and lower limits of the real values. 


@ This code declares two separate segment transformation matrixes. These 
matrixes are required for scaling the boxes. 


@® The next lines of code draw and label each of the boxes. The two boxes 


are segments 1 and 2. The upper triangle within each box has a pick 
identifier of 1, and the other triangles have a pick identifier of 2. 
This code initializes the pick logical input device with the requested 
input values. 
This code initializes the valuator logical input device with the requested 
input values. The upper limit of the real values is 1.5, which increases 
the size of the box by 50 percent. The lower limit is 0.5, which decreases 
the size of the box by 50 percent. 

@ The WHILE loop calls the SCALE_IT subroutine until the user picks the 
second pick identifier (the lower triangle labelled STOP) in the second 
segment. 
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@ This code calls the OVERFLOW subroutine in the event of an event 
input queue overflow. Section 7.5.3.3 describes this subroutine in detail. 


© The file GKSMSGS.FOR contains the constants that correspond with the 
DEC GKS error messages. The application includes this file to check for 
an error caused by the event input queue overflow. 


© This WHILE loop gets information from the current event report 
depending on the value of the input_class argument established in the 
previous call to AWAIT EVENT. The loop checks for simultaneous events 
(multiple events entered in the queue by a single firing of a trigger) 
using a call to INQUIRE MORE SIMULTANEOUS EVENTS. If more 
simultaneous events exist, this code calls AWAIT EVENT to remove the 
event from the queue and process the information according to the input 
class of the device that generated the event. This loop continues until 
there are no more simultaneous events. 


@ This code checks to make sure that the input values would make a 
change to the current picture. (For instance, if the scaling factor is 
1.0, then the application does not scale the segment.) If the values are 
appropriate, this code creates the corresponding segment transformation 
matrix and then scales the segment. 


Figure 7—9 illustrates the effects of the program example before the user 
triggers any input; both of the logical input devices display their prompts. 
Figure 7-10 shows the workstation surface if the user presses the PF1 
key; only the valuator device is active and displaying a prompt. DEC 

GKS determines in which order to place the devices in the input cycle. 
Figure 7-11 shows the workstation surface if the user presses the PF1 key 
again; only the pick device is active and displaying a prompt. Figure 7-12 
shows the effects of generating events on both devices. Notice that the user 
has control over which input values are accepted (placed on the input queue 
by triggering the device); using sample mode, the application program has 
control over which input values are accepted (at the time of sampling). 
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Figure 7-9: Placing Two Devices in Event Mode—VT241 


Move the cursor to scale a box, 
PF1 cycles input devices. 

PF2 activates all devices. 

To finish, pick STOP. 
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Figure 7-10: Placing Two Devices in Event Mode—VT241 


Move the cursor to scale a box, 
PFi cycles input devices, 

PF2 activates ali devices, 

To finish, pick STOP, 
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Figure 7-11: Placing Two Devices in Event Mode—VT241 


Move the cursor to scale a box, 
PFL cycles input devices, 

PF2 activates all devices, 

To finish, pick STOP, 
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Figure 7-12: Placing Two Devices in Event Mode—VT241 
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7.5.3.3 Event Input Queue Overflow 


Since the user can generate events as soon as you call one of the functions 
SET LOCATOR MODE, SET STROKE MODE, and so forth, it is possible for 
the user to fill the event input queue before the application has the chance 
to remove any of the event reports. 


If you attempt to call either AWAIT EVENT or FLUSH DEVICE EVENTS 
in this situation, then DEC GKS logs an initial event input queue overflow 
error (GKS$K_ERROR_147—Input queue has overflowed). If you continue 
to call either AWAIT EVENT or FLUSH DEVICE EVENTS, the functions 
still perform their task but the logical input devices cannot accept additional 
input until you clear the input queue. Since you can generate error 
GKS$K_ERROR_147 many times while attempting to clear the queue, DEC 
GKS logs the error only once, the first time it occurs. 


To test for input queue overflow, you can call the function INQUIRE INPUT 
QUEUE OVERFLOW immediately after a call to AWAIT EVENT. If the 
error_status argument to INQUIRE INPUT QUEUE OVERFLOW is equal 
to the value 0, then the following is true. 
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e The event input queue has overflowed. 
¢ Information about the overflow is available. 
e INQUIRE INPUT QUEUE OVERFLOW writes the workstation identi- 


fier, the input class, and the logical device number of the device that last 
accepted input to its output arguments. 


If the error_status argument to INQUIRE INPUT QUEUE OVERFLOW is | 
not equal to the value 0, then the information needed to write to the output 
arguments is not available. In this case, the error_status argument can 
equal one of the following values. 


¢ GKS$K_ERROR_7—GKS not in proper state. 

¢ GKS$K_ERROR_148—Input queue has not overflowed since GKS 
was opened or since the last invocation of INQUIRE INPUT QUEUE 
OVERFLOW. 


¢ GKS$K_ERROR_149—Input queue has overflowed, but the associated 
workstation has been closed. 


If the event input queue overflows, you can continue to call AWAIT EVENT, 
removing the reports one by one until a call returns GKS$K_INPUT_ 
CLASS_NONE. As a second option, you can call the function FLUSH 
DEVICE EVENTS to remove the remaining reports generated by a 

device of a single input class. By calling FLUSH DEVICE EVENTS for all 
possible logical input classes, you clear the buffer and allow the user to enter 
input again. 


Example 7—5 presents one method of handling an event input queue 
overflow. 
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Example 7-5: Subroutine Handling Event Queue Overflow 





Cc Check for queue overflow. 
CALL GKSS$INQ_INPUT_QUEUE_OVERFLOW( ERROR_STATUS, WS_ID, 
* CLASS, DEVICE_NUM ) 


Cc If the event input queue has overflowed... 
tt] IF ( ERROR_STATUS .EQ. 0 ) THEN 
CALL OVERFLOW( WS_ID, CLASS, DEVICE_NUM, PICK_INPUT STATUS, 
* SEGMENT, PICK_ID, XFORM_MATRIX1, XFORM_MATRIX2 ) 
ENDIF 
Cc EEE REE RAED AR AAEEE SEAS ER ENGST EERIE OAGREEAE WAR RAR 
Cc Take care of the input. queue overflow... 


SUBROUTINE OVERFLOW( WS_ID, CLASS, DEVICE_NUM, 
* PICK_INPUT_STATUS, SEGMENT, PICK_ID, XFORM MATRIX1, 
* XFORM MATRIX2 ) 


IMPLICIT NONE 

INCLUDE ’SYSS$LIBRARY:GKSDEFS.FOR’ 

INTEGER CLASS, PICK_INPUT STATUS, WS_ID, DEVICE_NUM, 
* PICK_ID, SEGMENT 

REAL VALUE, XFORM MATRIX1( 6 ), XFORM_MATRIX2( 6 ) 


Cc Stop any further input. 
e CALL GKS$SET_PICK_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_REQUEST, GKS$K_ECHO ) 
CALL GKS$SET_VALUATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE REQUEST, GKSS$K_ECHO ) 


© DO WHILE (( CLASS .NE. GKSSK_INPUT_CLASS_NONE) .AND. 
* ( CLASS .NE. GKS$K_INPUT_CLASS PICK )) 
Cc Check the event queue. 


CALL SCALE_IT( WS_ID, CLASS, DEVICE_NUM, PICK_INPUT_STATUS, 
* SEGMENT, PICK_ID, XFORM_MATRIX1, XFORM MATRIX2 ) 


ENDDO 


(continued on next page) 
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Cc 


Cc 


4) 


If there is a pick event left, read the report. 
IF ( CLASS .EQ. GKS$K_INPUT_CLASS PICK ) THEN 
CALL GKS$GET_PICK( PICK_INPUT_STATUS, SEGMENT, 
* PICK_ID ) 
ENDIF 


Flush the queue of all event reports. 


CALL GKS$FLUSH_DEVICE_EVENTS( WS_ID, 
* GKSS$K_INPUT_CLASS VALUATOR, DEVICE _NUM ) 
CALL GKS$FLUSH_DEVICE EVENTS( WS_ID, 
* GKS$K_INPUT_CLASS_PICK, DEVICE_NUM ) 


Notify the user and return to event mode... 


CALL GKSSREDRAW_SEG ON WS( WS_ID ) 

CALL GKSSTEXT( 0.05, 0.95, ‘You entered input too fast!’ ) 
CALL GKSSTEXT( 0.05, 0.90, ’Please enter the input again.’ ) 
CALL GKSSTEXT( 0.05, 0.85, '’Press RETURN when ready.’ ) 

CALL GKSSUPDATE_WS ( Ws_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 


CALL GKS$SET_PICK_MODE( WS_ID, DEVICE_NUM, 

* GKS$K_INPUT MODE EVENT, GKS$K_ECHO ) 

CALL GKS$SET_VALUATOR_MODE( WS ID, DEVICE_NUM, 
* GKSS$K_INPUT MODE EVENT, GKS$K_ECHO ) 


END 


The following numbers correspond to the numbers in the previous example: 


o 
e@ 


If the error_status argument to INQUIRE INPUT QUEUE OVERFLOW 
is the value 0, then there has been an overflow. 


You can stop the further generation of events by placing all logical 
input devices in request mode, thus removing the prompts from the 
workstation surface. 


This code removes each of the reports and scales the appropriate seg- 
ment until it reaches a pick event or the end of the queue. The effect is 
to obtain the next pick event report, if one exists on the queue. 


You can use FLUSH DEVICE EVENTS to remove all reports remaining 
in the queue. 


This code notifies the user as to the cause of the delay in processing and 
then places the devices back into event mode. At this point, the user can 
once again generate event reports. 
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7.6 Function Descriptions 


This section describes the DEC GKS input functions in detail. 
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Initializing Input 


This section describes the functions used to specify input values to the 
logical input devices. In order to initialize a logical input device, you need to 
make sure that the device’s prompt is not currently present on the surface 
of the workstation. So, to initialize a device, make sure that the device is in 
request mode (GKS$K_INPUT_MODE_REQUEST). This is the DEC GKS 
default mode. 


If the device is in request mode and you activate an input device without 
first calling one of the INITIALIZE class functions, the logical input device 
uses the device's default values (see Section 7.3.2 for more information). 


This section describes the following functions: 


INITIALIZE CHOICE 
INITIALIZE LOCATOR 
INITIALIZE PICK 
INITIALIZE STRING 
INITIALIZE STROKE 
INITIALIZE VALUATOR 
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INITIALIZE CHOICE 


Operating States: WSOP, WSAC, SGOP 


Description 


The function INITIALIZE CHOICE establishes the initial values of a choice 
class device only if the device’s prompt is not currently present on the 
workstation surface (the device must be in request mode). The initial values 
include the initial choice value, the prompt and echo type, the echo area, 
and the data record. Subsequent requests for choice input use the values 
you specify. 


Syntax 


GKSS$INIT_CHOICE (workstation_id, device_number, 
initial_status, initial_choice, 
prompt_echo_type, echo_area, data_record, 
size: of_record) 

GINCH  (workstation_id, device_number, in_status, in_choice, 

p_e_ltype, xmin, xmax, ymin, ymax, dim_dr, dr) 
ginitchoice (workstation_id, device_number, init, pet, area, 
record) 
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INITIALIZE CHOICE 

Arguments 

workstation_id 

data type: integer 

access: read-only 

mechanism: by reference 

This argument is the workstation identifier specified in a previous call to 

OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


initial_status 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the initial status of the logical input device. This 
argument determines whether a value is returned if the user triggers 
the request before moving the cursor. The argument can be either of the 
following constants or values: 


Value Constant Description 
1 GKS$K_STATUS_OK The initial choice is chosen. 
2 GKS$K_STATUS_NOCHOICE No value is returned. 


initial_choice 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the integer representing the initial highlighted choice. 
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prompt_echo_type 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the prompt and echo type. 


echo_area 

data type: array (real) 
access: read-only 
mechanism: by reference 


This argument is the echo area, which is a four-element array specifying 
the area on the workstation surface on which the prompt appears. Pass the 
device coordinates in the order X_MINIMUM, X_ MAXIMUM, Y_MINIMUM, 
Y_MAXIMUM. 


data_record 


data type: address (record) 
access: read-only 
mechanism: by reference 


This argument is a pointer to the data record whose size and contents 
are dependent on the prompt and echo type, and on the graphics handler 
requirements. Each workstation may require a different data record 
structure with different contents. 


size_of_record 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the amount of the data record buffer containing the actual 
data record, in bytes. 
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Error 
Number 


20 
25 


38 


46 
51 
120 
122 


123 


Completion 
Status Code 


DECGKS$_ERROR_NEG_20 
DECGKS$_ERROR_NEG_90 


DECGKS$_ERROR_NEG_93 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 


GKS$_ERROR_46 
GKS$_ERROR_51 
GKS$_ERROR_120 
GKS$_ERROR_122 


GKS$_ERROR_123 
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Message 


GKS not in proper state: GKS in 
the error state in routine **** 


Internal GKS error: Bad memory 
freed in routine **** 


Internal GKS error: Prompt and 


echo type not supported in routine 
eK 


GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** ~ 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Contents of input data record are 
invalid in routine **** 


Rectangle definition is invalid in 
routine **** 


Specified segment name is invalid 
in routine **** 


Specified segment does not exist in 
routine **** 


Specified segment does not exist 


on specified workstation in routine 
hk 
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Error 
Number 


140 


141 


144 


145 
146 


152 


Program Example 


Completion 
Status Code 


GKS$_ERROR_140 


GKS$_ERROR_141 


GKS$_ERROR_144 


GKS$_ERROR_145 
GKS$_ERROR_146 


GKS$_ERROR_152 


Message 


Specified input device is not 


present on workstation in routine 
Ree 


Input device is not in REQUEST 
mode in routine **** 


Specified prompt and echo type is 
not supported on this workstation 
in routine **** 


Echo area is outside display space 
in routine **** 


Contents of input data record are 
invalid in routine **** 


Initial value is invalid in routine 
KKK 


Example 7-6 illustrates the use of the function INITIALIZE CHOICE. 
Following the program example, Figure 7-13 illustrates the program’s effect 
on a VT241 workstation. 
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Cc 


aaa 


aaa 


Cc 


This program initializes and requests choice input from a VT241. 
IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS ID, DATA_RECORD( 3 ), NUM_CHOICES, SIZES( 3 ), 

* ADDRESSES ( 3 ), PROMPT ECHO TYPE, ERROR_STATUS, 

* INPUT MODE, ECHO FLAG, RECORD _BUFFER_LENGTH, RECORD _SIZE, 

* INPUT_STATUS, INITIAL CHOICE, DEVICE_NUM, INPUT _CHOICE, 
* INITIAL STATUS 


REAL ECHO AREA( 4 ) 


CHARACTER*80 CURRENT _STRINGS( 3 ) 
DATA WS_ID / 1 /, DEVICE_NUM / 1 / 


First element in the data record is the number of choices. 
EQUIVALENCE ( DATA_RECORD(1), NUM_CHOICES ) 

CALL GKSSOPEN_GKS ( ‘SYSSERROR:’ ) 

CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSS$ACTIVATE_WS( WS_ID ) 

Establish the size of the record buffer: 12 bytes. 
RECORD_BUFFER_LENGTH = 12 


The second element in the VT241 choice data record is the pointer to 
the array containing sizes of each choice character string. You need 
to initialize the pointer so that the array can be initialized. 


DATA_RECORD( 2 ) = %LOC( SIZES(1) ) 


The third element in the VT241 choice data record is the pointer to the 
array containing the pointers to the strings to be used. You need 

to initialize the pointer so that the array can be initialized. 
DATA_RECORD( 3 ) = %LOC( ADDRESSES(1) ) : 


ADDRESSES( 1 ) = %LOC( CURRENT_STRINGS( 1) ) 
ADDRESSES( 2 ) = %LOC( CURRENT_STRINGS( 2 ) ) 
ADDRESSES( 3 ) = %LOC( CURRENT _STRINGS( 3 ) ) 


Inquire about the default values. 
NUM_CHOICES = 3 


CALL GKS$INQ_CHOICE STATE( WS ID, DEVICE_NUM, 

* ERROR_STATUS, INPUT_MODE, ECHO FLAG, INITIAL STATUS, 
* INITIAL CHOICE, PROMPT ECHO TYPE, ECHO AREA, 

* DATA_RECORD, RECORD _BUFFER_LENGTH, RECORD SIZE ) 


(continued on next page) 
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Mode 


PROMPT ECHO TYPE = 1 
INITIAL CHOICE = 2 


C Establish sizes of prompt strings... 
SIZES( 1) = 6 
SIZES( 2 ) = 6 
SIZES( 3) =7 

Cc Establish locations of prompt strings... 
ADDRESSES( 1 ) = %SLOC( ‘Castro’ ) 


ADDRESSES ( 2 ) SLOC( ’Street’ ) 
ADDRESSES ( 3 ) $LOC( ‘’Station’ ) 
Cc Since the device is in request mode by default, initialize the device. 
7) CALL GKSS$INIT_CHOICE( WS_ID, DEVICE_NUM, 
* INITIAL STATUS, INITIAL CHOICE, PROMPT ECHO TYPE, 
* ECHO AREA, DATA_RECORD, RECORD _BUFFER_LENGTH ) 


18) CALL GKS$SET_CHOICE MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT MODE REQUEST, GKS$K_ECHO ) 


© CALL GKS$REQUEST_CHOICE( WS_ID, DEVICE_NUM, INPUT_STATUS, 
* INPUT CHOICE ) 


Cc Output the input choice number. 
WRITE (6,*) INPUT_CHOICE 
CALL GKS$DEACTIVATE_WS ( WS_ID ) 
CALL GKSSCLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 
END 


The following numbers correspond to the numbers in the previous example: 


@ For a VT241 choice logical input device with a prompt and echo type 
1, the data record contains three values: the number of choices, the 
address of an array containing the size of the prompt strings, and the 
address of an array containing the addresses of the prompt strings. 


@ The echo area variable is an array of real numbers representing the 
rectangular echo area, in device coordinates. The echo area defines a 
portion of the workstation surface on which the choice appears. 
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The program uses this array to store the current choice strings. If you 
do not initialize the elements in the array ADDRESSES to point to the 
elements in CURRENT_STRINGS, the function INQUIRE CHOICE 
DEVICE STATE does not have a buffer in which to write the current 
strings. . 

Before calling INQUIRE CHOICE DEVICE STATE, you must initialize 
three modifiable arguments: record_buffer_length, data_record 

( 2 ), data_record( 3 ), and the buffers for the current choice strings. The 
argument record_buffer_length tells DEC GKS the size of the buffer. The 
two components of data_record contain addresses that tell DEC GKS 
where to write the initial string addresses and the initial strings. If 
you do not initialize these three modifiable arguments, you generate an 
error. 


This code sets the number of choices to be the number 3. 


The function INQUIRE CHOICE DEVICE STATE initializes the vari- 
ables you need to pass to the input functions. After the function call, 
record_buffer_length contains the amount of the buffer filled with the 
written data record. If record_size is larger than record_buffer_length, 
then you know that the data record was truncated to fit into your 
declared buffer. 


@ The function INITIALIZE CHOICE initializes the choice logical input 


device. 


© The call to SET CHOICE MODE places the logical input device into 


request mode and enables echoing of the input. 


© The function REQUEST CHOICE prompts the user for input. The 


integral choice is written to the last argument. 


Figure 7-13 shows the screen of a VT241 terminal at the request for input. 
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Figure 7-13: Requesting Input from a Choice Logical Input Device— 
VT 
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INITIALIZE LOCATOR 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function INITIALIZE LOCATOR establishes the initial values of a 
locator class logical input device only if the device’s prompt is not currently 
present on the workstation surface (the device must be in request mode). 
The initial values include the world coordinates of the initial locator, the 
normalization transformation used to transform the initial locator point, 
the prompt and echo type, the echo area, and the data record. Subsequent 
requests for locator input use the values you specify. 


For more information about the locator position and echo types 2 and 3, see 
the Chapter 1, VAXstation Workstation Specifics, in the DEC GKS Device 
Specifics Reference Manual. 


If you do not call INITIALIZE LOCATOR before you request input from a 
locator logical input device, DEC GKS uses the default input values. 


GKSSINIT_LOCATOR (workstation_id, device_number, 
initial_x_value, initial_y_value, 
transformation_number, 
prompt_echo_type, echo_area, 
data_record, size_of_record) 

GINLC  (workstation_id, device_number, x_form, px, py, p_e_type, 

xmin, xmax, ymin, ymax, dim_dr, dr) 


ginitloc (workstation_id, device_number, init, pet, area, record) 
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workstation_id 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


initial x_value 
initial_y_value 


data type: real 
access: read-only 
mechanism: by reference 


These arguments are the real numbers representing the initial position of 
the prompt, in world coordinates. 


transformation_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the normalization transformation number used to 
transform the initial point from world coordinates to normalized device 
coordinates. 
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prompt_echo_type 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the prompt and echo type. 


echo_area 

data type: array (real) 
access: read-only 
mechanism: by reference 


This argument is the echo area, which is a four-element array specifying 
the area on the workstation surface on which the prompt appears. Pass the 
device coordinates in the order X_MINIMUM, X_MAXIMUM, Y_MINIMUM, 
Y_MAXIMUM. 


data_record 


data type: address (record) 
access: read-only 
mechanism: by reference 


This argument is a pointer to the data record whose size and contents 
are dependent on the prompt and echo type, and on the graphics handler 
requirements. Each workstation may require a different data record 
structure with different contents. 


size_of_record 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the amount of the data record buffer containing the actual 
data record, in bytes. 
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20 
25 


38 


46 
51 
60 
63 
65 
80 


84 
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Completion 
Status Code 


DECGKS$_ERROR_NEG_20 


DECGKS$_ERROR_NEG_93 
GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 


GKS$_ERROR_46 
GKS$_ERROR_51 
GKS$_ERROR_60 
GKS$_ERROR_63 
GKS$_ERROR_65 
GKS$_ERROR_80 


GKS$_ERROR_84 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


Internal GKS error: Prompt and 


echo type not supported in routine 
HK 


GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 

Specified workstation is not open 
in routine **** 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Contents of input data record are 
invalid in routine **** 


Rectangle definition is invalid in 
routine **** 

Polyline index is invalid in routine 
REE 

Linetype is equal to zero in rou- 
tine woe 

Linewidth scale factor is less than 
zero in routine **** 

Fill area index is invalid in routine 
eek 


Style (pattern or hatch) index is 
equal to zero in routine **** 


Error 
Number 


92 


140 


141 


144 


145 


152 
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Completion 
Status Code 


GKS$_ERROR_92 


GKS$_ERROR_140 


GKS$_ERROR_141 


GKS$_ERROR_144 


GKS$_ERROR_145 


GKS$_ERROR_152 
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Message 


Color index is less than zero in 
routine **** 


Specified input device is not 
present on workstation in routine 
hk 

Input device is not in REQUEST 
mode in routine **** 

Specified prompt and echo type is 
not supported on this workstation 
in routine **** 

Echo area is outside display space 
in routine **** 


Initial value is invalid in routine 
sesh skeak 


To see an example of a call to this function, refer to Example 7-1. 
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INITIALIZE PICK 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function INITIALIZE PICK establishes the initial values of a pick class 
logical input device only if the device’s prompt is not currently present on 
the workstation surface (the device must be in request mode). The initial 
values include the initial status value, the initial segment, the initial pick 
identifier, the prompt and echo type, the echo area, and the data record. 
Subsequent requests for pick input use the values you specify. 


If you do not call INITIALIZE PICK before you request input from a pick 
logical input device, DEC GKS uses the default input values. For more 
information concerning the default input values, refer to the DEC GKS 
Device Specifics Reference Manual. 


GKSSINIT_PICK (workstation_id, device_number, 
initial_status, initial_segment, initial_pick_id, 
prompt_echo_type, echo_area, data_record, 
size_of_record) 

GINPK (workstation_id, device_number, istatus, isegment, 

i_pick_id, p_e_type, xmin, xmax, ymin, ymax, dim_dr, dr) 
ginitpick (workstation_id, device_number, init, pet, area, record) 
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Arguments 

workstation_id 

data type: integer 

access: read-only 

mechanism: by reference 

This argument is the workstation identifier specified in a previous call to 

OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class, operating on the same workstation. 


initial_status 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the initial status of the logical input device. This 
argument determines whether a value is returned if the user triggers 
the request before moving the cursor. The argument can be either of the 
following constants or values: 


Value Constant Description 

1 GKS$K_STATUS_OK The initial segment and pick identifier 
are chosen. 

2 GKS$K_STATUS_NOPICK No segment or pick identifier is returned. 
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initial_segment 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the segment identifier that tells DEC GKS on which 
segment to place the prompt initially. 


initial_pick_id 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the pick identifier used to tell DEC GKS where in the 
chosen segment to place the prompt initially. A pick identifier is an integer 
that represents a portion of segment, allowing you to pick primitives instead 
of picking the entire segment. 


prompt_echo_type 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the prompt and echo type. 


echo_area 

data type: array (real) 
access: read-only 
mechanism: by reference 


This argument is the echo area, which is a four-element array specifying 
the area on the workstation surface on which the prompt appears. Pass the 
device coordinates in the order X_MINIMUM, X_MAXIMUM, Y_MINIMUM, 
Y_MAXIMUM. 


data_record 


data type: address (record) . 
access: read-only 
mechanism: by reference 


This argument is a pointer to the data record whose size and contents 
are dependent on the prompt and echo type, and on the graphics handler 
requirements. Each workstation may require a different data record 
structure with different contents. 
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access: 


mechanism: 
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This argument is the amount of the data record buffer containing the actual 
data record, in bytes. 


Error Messages 


Error 
Number 


-20 


~93 


20 
25 
37 
46 
51 


140 


Completion 
Status Code 


DECGKS$_ERROR_NEG_20 


DECGKS$_ERROR_NEG_93 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_37 
GKS$_ERROR_46 
GKS$_ERROR_51 


GKS$_ERROR_140 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


Internal GKS error: Prompt and 


echo type not supported in routine 
KEK 


GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is not of 
category OUTIN in routine **** 


Contents of input data record are 
invalid in routine **** 


Rectangle definition is invalid in 
routine **** 


Specified input device is not 


present on workstation in routine 
Crt 
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Error Completion 
Number Status Code 


141 


144 


145 


152 


GKS$_ERROR_141 


GKS$_ERROR_144 


GKS$_ERROR_145 


GKS$_ERROR_152 
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Message 


Input device is not in REQUEST 
mode in routine **** 


Specified prompt and echo type is 
not supported on this workstation 
in routine **** 


Echo area is outside display space 
in routine **** 


Initial value is invalid in routine 
KEK 


Example 7-7 illustrates the use of the function INITIALIZE PICK. 
Following the program example, Figure 7—14 illustrates the program’s effect 
on a VT241 workstation. 


Example 7-7: Using a Pick Logical Input Device in Request Mode 


This program initializes and requests pick input from a VT241. 


IMPLICIT NONE 


INCLUDE ’SYSS$LIBRARY:GKSDEFS.FOR’ 


INTEGER WS_ID, INITIAL STATUS, SEGMENT, 


+ He 


TRIANGLE 2, NUM POINTS 


REAL ECHO AREA(4), DATA_RECORD( 1 ) 
REAL X_VALUES( 4 ), Y_VALUES( 4 ) 


PICK_ID, PROMPT ECHO TYPE, ERROR_STATUS, 
INPUT_MODE, ECHO FLAG, RECORD_BUFFER_LENGTH, 
RECORD_SIZE, INPUT_STATUS, 

DEVICE_NUM, BOX_1, BOX_2, TRIANGLE_1, 


DATA WS_ID / 1 /, DEVICE_NUM / 1 /, BOX.1/1//, 
* BOX_2 / 2 /, TRIANGLE_1 / 1 /, TRIANGLE_2 / 2 /, 


* NUM POINTS / 4 / 


DATA X_VALUES / 0.1, 0.4, 0.1, 0 
DATA Y_VALUES / 0.3, 0.6, 0.6, 0 
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CALL GKSS$OPEN_GKS( ‘SYSSERROR:’ ) 
CALL GKS$OPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE WS( WS_ID ) 


CALL GKS$SET_FILL_INT_STYLE( GKS$K_INTSTYLE_SOLID ) 


CALL GKS$CREATE_SEG( BOX_1 ) 

CALL GKS$SET_PICK_ID( TRIANGLE 1 ) 

CALL GKS$SET FILL COLOR_INDEX( 2 ) 

CALL GKS$FILL_AREA( NUM POINTS, X_VALUES, Y_VALUES ) 
X_VALUES( 3) = 0.4 

Y_VALUES( 3 ) = 0.3 

CALL GKS$SET_PICK_ID( TRIANGLE 2 ) 

CALL GKS$SET FILL COLOR_INDEX( 3 ) 

CALL GKSS$FILL_AREA( NUM POINTS, X_VALUES, Y_VALUES ) 
CALL GKS$CLOSE_SEG() 


X_VALUES( 1) = 
X_VALUES( 2) = 


X_VALUES( 3 ) = 
X_VALUES( 4 ) = 0. 
Y_VALUES( 3) = 0. 


CALL GKS$SET_PICK_ID( TRIANGLE_1 ) 


CALL GKS$CREATE_SEG( BOX_2 ) 

CALL GKS$SET_FILL COLOR_INDEX( 2 ) 

CALL GKS$FILL_AREA( NUM POINTS, X_VALUES, Y_VALUES ) 
X_VALUES( 3 ) = 0.9 

Y_VALUES( 3 ) = 0.3 

CALL GKS$SET_PICK_ID( TRIANGLE 2 ) 

CALL GKS$SET_FILL_COLOR_INDEX( 3 ) 

CALL GKS$FILL_AREA( NUM_POINTS, X_VALUES, Y_VALUES ) 
CALL GKS$CLOSE_SEG () 


CALL GKS$SET_SEG DETECTABILITY ( BOX_1, GKS$K_DETECTABLE ) 
CALL GKS$SET_SEG_ DETECTABILITY ( BOX_2, GKS$K_DETECTABLE ) 


CALL GKSSSET_TEXT HEIGHT( 0.03 ) 
CALL GKSSTEXT( 0.2, 0.45, ‘’17) 
CALL GKSS$TEXT( 0.3, 0.45, '2’) 
CALL GKSSTEXT( 0.7, 0.45, '17) 
CALL GKSSTEXT( 0.8, 0.45, '2’) 


(continued on next page) 
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Example 7-7 (Cont.): Using a Pick Logical Input Device in Reqhest Mode 





Cc Declare a data length of one long word which will hold the 
Cc size of the pick prompt. 
© RECORD _BUFFER_LENGTH = 4 


CALL GKSSINQ_PICK_STATE( WS_ID, DEVICE_NUM, 


* GKS$K_VALUE_REALIZED, ERROR_STATUS, INPUT_MODE, 
* ECHO FLAG, INITIAL STATUS, SEGMENT, PICK_ID, 
* PROMPT ECHO TYPE, ECHO AREA, DATA_RECORD, 
* RECORD _BUFFER_LENGTH, RECORD_SIZE ) , 
7] SEGMENT = BOX_1 
PICK_ID = TRIANGLE_1 


PROMPT ECHO TYPE = 1 
INITIAL STATUS = GKS$K_STATUS_NOPICK 
c Since the device is in request mode by default, initialize the device. 


8] CALL GKSSINIT_PICK( WS_ID, DEVICE_NUM, INITIAL STATUS, 
* SEGMENT, PICK_ID, PROMPT ECHO TYPE, ECHO_AREA, 
* DATA RECORD, RECORD BUFFER_LENGTH ) 


© CALL GKS$SET_PICK_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT MODE REQUEST, GKS$K_ECHO ) 


® CALL GKSSREQUEST PICK( WS_ID, DEVICE_NUM, INPUT_STATUS, 
* SEGMENT, PICK_ID ) 


c Output the segment number and pick identifier. 
WRITE (6,*) INPUT_STATUS, SEGMENT, PICK_ID 
CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKSSCLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 
END 


The following numbers correspond to the numbers in the previous example: 


@ The DEC GKS VT241 handler requires a data record for prompt and 
echo type 1 that contains a real value (size of the pick aperture prompt 
in device coordinates). 


The echo area variable is an array of real numbers representing the 
rectangular echo area, in device coordinates. The echo area defines a 
portion of the workstation surface on which the prompt moves. 


@ This code creates a box on the left side of the workstation surface and 
places it in a segment. The code divides the box diagonally and sets pick 
identifiers for each of the created triangles. 
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This code resets the X and Y world coordinate values so that the position 
of the box changes. 


This code creates a box on the right side of the workstation surface and 
places it in a segment. The code divides the box diagonally and sets pick 
identifiers for each of the created triangles. 

This code labels the triangles by their pick identifiers. 


The function INQUIRE PICK DEVICE STATE initializes the variables 
you need to pass to the input functions. The argument GKS$K_VALUE_ 
REALIZED tells the graphics handler to pass the input values as they 
are implemented, as opposed to the way that the application may have 
set the values (GKS$K_VALUE_SET). 


After the function call, record_buffer_length contains the amount of the 
buffer filled with the written data record. If record_size is larger than 
record_buffer_length, then you know that the data record was truncated 
to fit into your declared buffer. 


This code assigns new values to the input variables. For instance, the 
initial segment identifier has the value 1. 
The function INITIALIZE PICK initializes the request for choice input. 


The call to SET PICK MODE places the logical input device into request 
mode and enables echoing of the input. 


The function REQUEST PICK prompts the user for input. The segment 
and pick identifiers are written to the last arguments. 


Figure 7-14 shows the screen of a VT241 terminal at the request for input. 
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Figure 7-14: Requesting Input from the Pick Input Device—VT241 
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INITIALIZE STRING 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function INITIALIZE STRING establishes the initial values of a string 
class logical input device only if the device’s prompt is not currently present 
on the workstation surface (the device must be in request mode). The initial 
values include the initial string value, the prompt and echo type, the echo 
area, and the data record. Subsequent requests for choice input use the 
values you specify. 


If you do not call INITIALIZE STRING before you request input from the 
string logical input device, GKS uses the default input values. 


GKSSINIT_STRING (workstation_id, device_number, 
initial_string, prompt_echo_type, echo_area, 
data_record, size_of_record) 

GINST (worksiation_id, device_number, Istring, istring, p_e_type, 

xmin, xmax, ymin, ymax, buf_len, i_cur_pos, dim_dr, dr) 

GINST - Subset (workstation_id, device_number, Istring, istring, 

p_e_type, xmin, xmax, ymin, ymax, buf_len, 
i_cur_pos, dim_dr, dr) 


ginitstring (workstation_id, device_number, init, pet, area, record) 
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INITIALIZE STRING 

Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 
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This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


initial_string 


data type: string 
access: read-only 
mechanism: by descriptor 


This argument is the initial string displayed on the workstation surface. 
Once you request input, the user can delete or edit the initial string; 
otherwise, the newly input string is appended to the initial string. 


prompt_echo_type 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the prompt and echo type. 


echo_area 

data type: array (real) 
access: read-only 
mechanism: by reference 


This argument is the echo area, which is a four-element array specifying 
the area on the workstation surface on which the prompt appears. Pass the 
device coordinates in the order X_MINIMUM, X_MAXIMUM, Y_MINIMUM, 
Y_MAXIMUM. 
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data_record 


data type: address (record) 
access: read-only 
mechanism: by reference 


This argument is a pointer to the data record whose size and contents 

are dependent on the prompt and echo type, and on the graphics handler 
requirements. Each workstation may require a different data record 
structure with different contents. Refer to the DEC GKS Device Specifics 
Reference Manual for more information concerning the device’s data record 
requirements. 


size_of_record 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the amount of the data record buffer containing the actual 
data record, in bytes. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

—34 DECGKS$_ERROR_NEG_34 String length less than or equal to 

. 0 in routine **** 

—93 DECGKS$_ERROR_NEG_93 _ Internal GKS error: Prompt and 
echo type not supported in routine 
KER 

7 GKS$_ERROR_7 GKS not in proper state; GKS 


shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 
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Error 
Number 


20 
25 


38 


46 
51 


140 


141 


144 


145 
152 


154 
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Completion 
Status Code 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 


GKS$_ERROR_46 
GKS$_ERROR_51 


GKS$_ERROR_140 


GKS$_ERROR_141 


GKS$_ERROR_144 


GKS$_ERROR_145 
GKS$_ERROR_152 


GKS$_ERROR_154 


Message 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Contents of input data record are 
invalid in routine **** 


Rectangle definition is invalid in 
routine **** 


Specified input device is not 


present on workstation in routine 
RR 


Input device is not in REQUEST 
mode in routine **** 


Specified prompt and echo type is 
not supported on this workstation 
in routine **** 


Echo area is outside display space 
in routine **** 

Initial value is invalid in routine 
Re 

Length of the initial string is 
greater than the buffer size in 
routine **** 


Example 7-8 illustrates the use of the function INITIALIZE STRING. 
Following the program example, Figure 7-15 illustrates the program’s effect 
on a VT241 workstation. 
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Cc 


Cc 


6 


This program initializes and requests string input from a VT241. 
IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, DATA_RECORD( 2 ), 

* PROMPT_ECHO TYPE, ERROR_STATUS, BUFFER_LENGTH, 

* INPUT_MODE, ECHO FLAG, RECORD BUFFER_LENGTH, 

* RECORD SIZE, INPUT_STATUS, DEVICE_NUM, STRING_SIZE, 

* CUR_POSITION 


REAL ECHO AREA( 4 ) 


CHARACTER*80 INITIAL STRING, INPUT_STRING 
DATA WS_ID / 1 /, DEVICE_NUM / 1 / 


First element in the data record is length of the buffer that 
contains the input string. 

EQUIVALENCE ( DATA_RECORD( 1 ), BUFFER_LENGTH ) 

EQUIVALENCE ( DATA_RECORD( 2 ), CUR_POSITION ) 

CALL GKSSOPEN_GKS( ’SYSSERROR:’ ) 

CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE_WS( WS_ID ) 

RECORD _BUFFER_LENGTH = 8 


CALL GKSS$INQ_STRING_STATE( WS_ID, DEVICE_NUM, 

* ERROR_STATUS, INPUT_MODE, ECHO FLAG, INITIAL STRING, 

* STRING_SIZE, PROMPT ECHO TYPE, ECHO AREA, DATA_RECORD, 
* RECORD _BUFFER_LENGTH, RECORD_SIZE ) 


BUFFER_LENGTH = 15 
PROMPT ECHO TYPE = 1 


Since the device is in request mode by default, initialize the device. 


CALL GKS$INIT_STRING( WS_ID, DEVICE _NUM, ‘GKS>’, 
* PROMPT ECHO TYPE, ECHO AREA, DATA RECORD, 
* RECORD BUFFER_LENGTH ) 


CALL GKS$SET_STRING_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE REQUEST, GKS$K_ECHO ) 


(continued on next page) 
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* INPUT STRING, STRING SIZE ) 


Cc Output the input string and its size. 
WRITE (6, *) INPUT STRING, STRING SIZE 
CALL GKS$DEACTIVATE_WS ( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 
END 


The following numbers correspond to the numbers in the previous example: 


@ For all logical input prompt and echo types, the data record contains 
the length of the buffer and the initial editing position . This buffer can 
only be as large as the maximum size supported by the workstation. To 
obtain that size, you can call INQUIRE DEFAULT STRING DEVICE 
DATA. 


@ The echo area variable is an array of real numbers representing the 
rectangular echo area, in device coordinates. The echo area defines a 
portion of the workstation surface on which the initial string appears. 


© The defined string variables can contain a string the length of the 
terminal screen. You can alter the maximum size of the input string, 
every time you initialize the string logical input device, by changing the 
value associated with the buffer length. 

© The function INQUIRE STRING DEVICE STATE initializes the vari- 
ables you need to pass to the input functions. After the function call, 
record_buffer_length contains the amount of the buffer filled with the 
written data record. If record_size is larger than record_buffer_length, 


then you know that the data record was truncated to fit into your 
declared buffer. 


@ This code assigns new values to the input variables. For instance, the 
buffer length is defined to be 15 bytes. 


@ The function INITIALIZE STRING initializes the string logical input 
device. 
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@ The call to SET STRING MODE places the logical input device into 
request mode and enables echoing of the input. 


@® The function REQUEST STRING prompts the user for input. The input 
string is written to the second to last argument. The last argument 
contains the size of the input string. 


Figure 7-15 shows the screen of a VT241 terminal at the request for input. 


Figure 7-15: Requesting from the String Logical Input Device—VT241 
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INITIALIZE STROKE 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function INITIALIZE STROKE establishes the initial values of a stroke 
class logical input device only if the device’s prompt is not currently present 
on the workstation surface (the device must be in request mode). The 
initial values include the number of points in the initial stroke, the world 
coordinate values in the initial stroke, the normalization transformation 
number used to translate world coordinates of the initial stroke to NDC 
points, the prompt and echo type, the echo area, and the data record. 
Subsequent requests for choice input use the values you specify. 


If you do not call INITIALIZE STROKE before you request input from a 
stroke logical input device, DEC GKS uses the default input values. 


GKSS$INIT_STROKE  (workstation_id, device_number, 
initial_num_points, initial_stroke_x_values, 
initial_stroke_y_values, 
transformation_number, prompt_echo_type, 
echo_area, data_record, size_of_record) 


GINSK (workstation_id, device_number, xform, num_pts, px, py, 
p_e_type, xmin, xmax, ymin, ymax, buf_len, dim_dr, dr) 
ginitstroke (workstation_id, device_number, init, pet, area, 
record) 
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INITIALIZE STROKE 

Arguments 

workstation_id 

data type: integer 

access: read-only 

mechanism: by reference 

This argument is the workstation identifier specified in a previous call to 

OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


initial_number_points 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the number of points in the initial stroke. 


initial_stroke_x_values 
initial_stroke_y values 


data type: array (real) 

access: read-only 

mechanism: by reference 

These arguments are the X and Y world coordinate values in the initial 
stroke. 


transformation_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the normalization transformation number used to 
transform the initial stroke from world coordinates to normalized device 
coordinates. 
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prompt_echo_type 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the prompt and echo type. 


echo_area 

data type: (real) 

access: read-only 
mechanism: by reference 


This argument is the echo area, which is a four-element array specifying 
the area on the workstation surface on which the prompt appears. Pass the 
device coordinates in the order X_MINIMUM, X_MAXIMUM, Y_MINIMUM, 
Y_MAXIMUM. 


data_record 


data type: address (record) 
access: read-only 
mechanism: by reference 


This argument is a pointer to the data record whose size and contents 
are dependent on the prompt and echo type, and on the graphics handler 
requirements. Each workstation may require a different data record 
structure with different contents. 


size_of_record 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the amount of the data record buffer containing the actual 
data record, in bytes. 
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20 
25 


38 


46 
51 
60 
63 
65 


66 


Completion 
Status Code 
DECGKS$_ERROR_NEG_20 


DECGKS$_ERROR_NEG_93 
GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 


GKS$_ERROR_46 
GKS$_ERROR_51 
GKS$_ERROR_60 
GKS$ _ERROR_63 
GKS$_ERROR_65 


GKS$_ERROR_66 
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Message 


GKS not in proper state: GKS in 
the error state in routine **** 


Internal GKS error: Prompt and 
echo type not supported in routine 
eK 

GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Contents of input data record are 
invalid in routine **** 


Rectangle definition is invalid in 
routine **** 


Polyline index is invalid in routine 
setae 


Linetype is equal to zero in rou- 
tine **** 


Linewidth scale factor is less than 
zero in routine **** 


Polymarker index is invalid in 
routine **** 
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Error 
Number 


67 


69 
92 


140 


141 


144 


145 
152 


153 


Program Example 


Completion 
Status Code 


GKS$_ERROR_67 


GKS$_ERROR_69 
GKS$_ERROR_92 


GKS$_ERROR_140 


GKS$_ERROR_141 


GKS$_ERROR_144 


GKS$_ERROR_145 
GKS$_ERROR_152 


GKS$_ERROR_153 


Message 


A representation for the specified 
polymarker index has been defined 
on this workstation in routine *** 
* 


Marker type is equal to zero in 
routine **** 


Color index is less than zero in 
routine **** 


Specified input device is not 


present on workstation in routine 
KE 


Input device is not in REQUEST 
mode in routine **** 


Specified prompt and echo type is 
not supported on this workstation 
in routine **** 


Echo area is outside display space 
in routine **** 


Initial value is invalid in routine 
KEKE 


The number of points in the initial 
stroke is greater than the buffer 
size in routine **** 


Example 7-9 illustrates the use of the function INITIALIZE STROKE. 
Following the program example, Figure 7-16 illustrates the program’s effect 
on a VT241 workstation. 
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Example 7-9: Using a Stroke Logical Input Device in Request Mode 


C This program initializes and requests stroke input from a VT241. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
0 INTEGER WS_ID, DATA_RECORD( 6 ), BUFFER_SIZE, 
DIMENSION, PROMPT ECHO TYPE, ERROR_STATUS, 
TRANSFRM, NUM_POINTS, INPUT_MODE, ECHO_FLAG, 
RECORD BUFFER_LENGTH, RECORD SIZE, INPUT STATUS, DEVICE _NUM, 
RET SIZE X, RET SIZE Y, I, EDIT POSITION, ATTS FLAG 
2] REAL ECHO AREA( 4 ), STROKE X( 50 ), 
* STROKE _Y( 50 ), X_INT, Y_INT, TIME_INT 
DATA WS_ID / 1 /, DEVICE_NUM / 1 / 


e+ + 


Cc First element in the data record is the buffer size. 
EQUIVALENCE ( DATA_RECORD( 1 ), BUFFER_SIZE) 
EQUIVALENCE ( DATA_RECORD( 2 ), EDIT_POSITION) 
EQUIVALENCE ( DATA_RECORD( 3 ), X_INT) 

EQUIVALENCE ( DATA_RECORD ( 4), Y_INT) 
EQUIVALENCE ( DATA_RECORD( 5 ), TIME INT) 
EQUIVALENCE ( DATA_RECORD( 6 ), ATTS FLAG) 


CALL GKSSOPEN_GKS( 'SYS$ERROR:’ ) 

CALL GKSS$OPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE_WS( WS_ID ) 

RECORD _BUFFER_LENGTH = 24 


3) CALL GKS$INQ_STROKE_STATE( WS_ID, DEVICE_NUM, 
GKS$K_VALUE_REALIZED, DIMENSION, ERROR_STATUS, 

INPUT MODE, ECHO FLAG, TRANSFRM, NUM_POINTS, STROKE_X, 
STROKE_Y, PROMPT ECHO TYPE, ECHO_AREA, DATA_RECORD, 
RECORD BUFFER_LENGTH, RECORD SIZE ) 


* % % 


4) BUFFER_SIZE = 256 
PROMPT ECHO TYPE = 1 


Cc By specifying to DEC GKS to use the current attributes flag, you 
Cc need to pass the 24 byte data record instead of the 52 byte record. 
ATTS FLAG = GKS$K_ACF_CURRENT 


(continued on next page) 
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Example 7-9 (Cont.): Using a Stroke Logical Input Device in Request 
Mode 


C Since the device is in request mode by default, initialize the device. 


5] CALL GKSS$INIT_STROKE( WS_ID, DEVICE_NUM, 
* NUM_POINTS, STROKE _X, STROKE_Y, TRANSFRM, 


* PROMPT ECHO TYPE, ECHO_AREA, DATA_RECORD, 
* RECORD _BUFFER_LENGTH ) 


© CALL GKS$SET_STROKE MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT MODE REQUEST, GKS$K_ECHO ) 


7] CALL GKS$REQUEST STROKE( WS_ID, DEVICE_NUM, 
* INPUT_STATUS, TRANSFRM, NUM POINTS, %DESCR( STROKE_X ), 
* %DESCR( STROKE_Y ), RET SIZE X, RET SIZE Y ) 


Cc Output the input stroke values. 
DO I = 1, RET SIZE_X, 1 
WRITE (6,*) STROKE_X( I ), STROKE_Y( I ) 
END DO 


CALL GKS$DEACTIVATE _WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 

CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ The DEC GKS VT241 reads the first six stroke data record components 
(24 bytes) for prompt and echo type 1. If the sixth component is 
GKS$K_ACF_CURRENT, then you must specify 24 bytes as the size 
of the record. If the sixth component is GKS$K_ACF_SPECIFIED, 
you need to pass the 52-byte record that contains all the attribute 
specifications. For more information, see Section 7.2.1, or refer to the 
DEC GKS Device Specifics Reference Manual. 


@ The echo area variable is an array of real numbers representing the 
rectangular echo area, in device coordinates. The echo area defines a 
portion of the workstation surface on which the prompt moves. 
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The function INQUIRE STROKE DEVICE STATE initializes the vari- 
ables you need to pass to the input functions. The argument 
GKS$K_VALUE_REALIZED tells the graphics handler to pass the in- 
put values as they are implemented, as opposed to the way that the 
application may have set the values (GKS$K_VALUE_SET)). 


After the function call, record_buffer_length contains the amount of the 
buffer filled with the written data record. If record_size is larger than 
record_buffer_length, then you know that the data record was truncated 
to fit into your declared buffer. 


This code assigns new values to the input variables. For instance, the 
buffer size is set to 256. To check the maximum allowable buffer size, 
call the function INQUIRE DEFAULT STROKE DEVICE DATA. 


© The function INITIALIZE STROKE initializes the request for stroke 


input. 


© The call to SET STROKE MODE places the logical input device into 


request mode and enables echoing of the input. 


The function REQUEST STROKE prompts the user for input. The 
stroke world coordinate values are written to the arguments of this 
function. 


Figure 7-16 shows the screen of a VT241 terminal at the request for input. 
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Figure 7-16: Requesting from the Stroke Logical Input Device—VT241 
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INITIALIZE VALUATOR 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function INITIALIZE VALUATOR establishes the initial values of a 
valuator class logical input device only if the device’s prompt is not currently 
present on the workstation surface (the device must be in request mode). 
The initial values include the initial valuator value, the prompt and echo 
type, the echo area, and the data record. Subsequent requests for choice 
input use the values you specify. 


If you do not call INITIALIZE VALUATOR before you request input from a 
valuator logical input device, DEC GKS uses the default input values. 


GKSS$INIT_VALUATOR § (workstation_id, device_number, 
initial_value, prompt_echo_type, 
echo_area, data_record, size_of_record) 


GINVL (workstation_id, device_number, ivalue, p_e_type, xmin, 
xmax, ymin, ymax, low_val, high_val, dim_dr, dr) 


ginitval (workstation_id, device_number, init, pet, area, record) 
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INITIALIZE VALUATOR 
Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 
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This argument is the workstation identifier apstinad’ in a previous call to 
OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


initial_value 


data type: real . 
access: read-only 
mechanism: by reference 


This argument is the real number representing the initial value. 


prompt_echo_type 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the prompt and echo type. 


echo_area 

data type: (real) 

access: read-only 
mechanism: by reference 


This argument is the echo area, which is a four-element array specifying 
the area on the workstation surface on which the prompt appears. Pass the 
device coordinates in the order X_MINIMUM, X_MAXIMUM, Y_MINIMUM, 
Y_MAXIMUM. 
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data_record 


data type: address (record) 
access: read-only 
mechanism: by reference 


This argument is a pointer to the data record whose size and contents 
are dependent on the prompt and echo type, and on the graphics handler 
requirements. Each workstation may require a different data record 
structure with different contents. 


size_of_record 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the amount of the data record buffer containing the actual 
data record, in bytes. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

—93 DECGKS$_ERROR_NEG_93 Internal GKS error: Prompt and 
echo type not supported in routine 
rhe 

7 GKS$_ERROR_7 GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 

20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 

25 GKS$_ERROR_25 Specified workstation is not open 


in routine **** 
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Error Completion 

Number - Status Code Message 

38 GKS$_ERROR_388 Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 

46 GKS$_ERROR_46 Contents of input data record are 
invalid in routine **** 

51 GKS$_ERROR_51 Rectangle definition is invalid in 
routine **** — 

140 GKS$_ERROR_140 Specified input device is not 
present on workstation in routine 
RR 

141 GKS$_ERROR_141 Input device is not in REQUEST 
mode in routine **** 

144. GKS$_ERROR_144 Specified prompt and echo type is _ 
not supported on this workstation 
in routine **** 

145 GKS$_ERROR_145 Echo area is outside display space 
in routine **** 

152 GKS$_ERROR_152 Initial value is invalid in routine 

. eR 


Program Example 


Example 7-10 illustrates the use of the function INITIALIZE VALUATOR. 
Following the program example, Figure 7-17 illustrates the program’s effect 
on a VT241 workstation. 
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Example 7—10: Using a Valuator Logical Input Device in Request Mode 





Cc This program initializes and requests valuator input from a VT241. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, PROMPT ECHO TYPE, ERROR_STATUS, 
* INPUT_MODE, ECHO FLAG, RECORD BUFFER_LENGTH, RECORD SIZE, 
* INPUT_STATUS, DEVICE_NUM 


REAL ECHO AREA( 4 ), DATA_RECORD( 2 ), UPPER_LIMIT, 
* LOWER_LIMIT, VALUE 


DATA WS_ID / 1 /, DEVICE_NUM / 1 / 


Cc The elements in the data record are the upper and lower limits. 
EQUIVALENCE ( DATA_RECORD( 1 ), LOWER_LIMIT ) 
EQUIVALENCE ( DATA_RECORD( 2 ), UPPER_LIMIT ) 
CALL GKSSOPEN_GKS( ’SYS$ERROR:’ ) 
CALL GKSSOPEN | _WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_' vT240 ) 
CALL GKSSACTIVATE _WS( WS_ID ) 


RECORD _BUFFER_LENGTH = 8 


CALL GKS$INQ_VALUATOR_STATE( WS ID, DEVICE_NUM, 
* ERROR STATUS, INPUT MODE, ECHO FLAG, VALUE, 

* PROMPT ECHO TYPE, ECHO_AREA, DATA_RECORD, 

* RECORD BUFFER_LENGTH, RECORD SIZE ) 


VALUE = 1.5 
UPPER_LIMIT 
LOWER_LIMIT 


3.0 
0.0 
PROMPT ECHO TYPE = 1 


Cc Since the device is in request mode by default, initialize the device. 


CALL GKSSINIT_VALUATOR( WS_ID, DEVICE_NUM, 
* VALUE, PROMPT ECHO TYPE, ECHO AREA, DATA_RECORD, 
* RECORD _BUFFER_LENGTH ) 


CALL GKSS$SET_VALUATOR_MODE( WS_ID, DEVICE_NUM, 
* GKSS$K_INPUT_MODE_ REQUEST, GKS$K_ECHO ) 


CALL GKSS$REQUEST_VALUATOR( WS_ID, DEVICE_NUM, 
* INPUT STATUS, VALUE ) 


Cc Output the input valuator number. 
WRITE (6,*) VALUE 
CALL GKSSDEACTIVATE WS( WS_ID ) 
CALL GKSSCLOSE_WS( WS_ID ) 
CALL GKSSCLOSE_GKS () 
END 
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The following numbers correspond to the numbers in the previous example: 


@ The echo area variable is an array of real numbers representing the 
rectangular echo area, in device coordinates. The echo area defines a 
portion of the workstation surface on which the prompt moves. 


The DEC GKS VT241 graphics handler uses two components of the 
valuator input data record for prompt and echo type 1: the real value 
representing an upper limit, and another real value representing a lower 
limit. 

@ The VT241 supports three valuator prompt and echo types represented 
by the integers 1, 2, and 3. Types 1 and 2 prompt the user with a 
rectangle and a horizontal scale. If using one of these types, the user 
moves an arrow, using the arrow keys, along the scale between the 
upper and lower limits. If using type 3, DEC GKS changes a single 
digital representation of the real values between the upper and lower 
limits, the user controlling the change of numbers using the arrow keys. 

© The function INQUIRE VALUATOR DEVICE STATE initializes the 

variables you need to pass to the input functions. After the function 
call, record_buffer_length contains the amount of the buffer filled with 
the written data record. If record_size is larger than record_buffer_ 
length, then you know that the data record was truncated to fit into your 
declared buffer. 

This code assigns new values to the input variables. For instance, the 

upper limit is set to the real value 3.0. 

The function INITIALIZE VALUATOR initializes the request for valua- 

tor input. 

The call to SET VALUATOR MODE places the logical input device into 

request mode and enables echoing of the input. 

The function REQUEST VALUATOR prompts the user for input. The 

input real value is written to the last argument. 


Figure 7-17 shows the screen of a VT241 terminal at the request for input. 
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Figure 7-17: Requesting from the Valuator Logical Input Device—VT241 





2K-5217-86 


Input Functions 7-103 


Setting Input Operating Modes 


Setting Input Operating Modes 


7-104 


This section describes the functions used to control prompt echoing and to 
change the input operating mode (see Section 7.5 for more information). 
You do not have to call these functions to initiate the input process. If you 
choose, you can call the appropriate request function (request is the default 
input operating mode for DEC GKS) and the logical input device echoes 
input by default. 


If you set the input operating mode to either sample or event mode, the 
input prompt appears on the workstation surface at the time that you call 
one of these functions. If you set the input operating mode to request, the 
prompt does not appear on the workstation surface until you call one of the 
REQUEST class functions. 


This section describes the following functions: 


e SET CHOICE MODE 
e SET LOCATOR MODE 


-@ SET PICK MODE 


e SET STRING MODE 
e SET STROKE MODE 
e SET VALUATOR MODE 
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SET CHOICE MODE 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SET CHOICE MODE establishes the operating mode of a 
choice logical input device, and determines whether DEC GKS echoes the 
prompt and input values on the workstation surface. 


Syntax 
GKS$SET_CHOICE_MODE (workstation_id, device_number, 
operating_mode, echo_flag) 
GSCHM = (workstation_id, device_number_num, operating_mode, 
echo) 
gsetchoicemode _ (workstation_id, device_number, 
operating_mode, echo) 
Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 
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device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


operating _mode 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the operating mode specifying the method of input. This 
argument can be any of the following values, according to the DEC GKS 
standard: 


Value Constant Description 

0 GKS$K_INPUT_MODE_REQUEST Request mode — 
1 GKS$K_INPUT_MODE_SAMPLE Sample mode 

2 GKS$K_INPUT_MODE_EVENT Event mode 
echo_flag 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the echo flag. This flag determines whether or not the 
prompt and input values are echoed on the workstation surface. This 
argument can be either of the following values or constants: 


Value Constant Description 
0 GKS$K_NOECHO Disable the echo. 
1 GKS$K_ECHO Enable the echo. 
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SET CHOICE MODE 
Error Messages 
Error Completion 
Number Status Code Message 
 =-16 DECGKS$_ERROR_NEG_16 Echo switch is invalid in routine 
KKK 
-20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 
7 GKS$_ERROR_7 GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 
20 GKS$_ERROR.20 Specified workstation identifier is 
invalid in routine **** 
25 GKS$_ERROR_25 Specified workstation is not open 
in routine **** 
38 GKS$_ERROR_38 Specified workstation is neither of 


category INPUT nor of category 
OUTIN in routine **** 


140 GKS$_ERROR_140 Specified input device is not 


present on workstation in routine 
RoR 


Program Example 


To see an example of a call to this function, refer to Example 7-6. 
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SET LOCATOR MODE 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SET LOCATOR MODE establishes the operating mode of a 
locator logical input device, and determines whether DEC GKS echoes the 
prompt and input values on the workstation surface. 


Syntax 
GKS$SET_LOCATOR_MODE § (workstation_id, device_number, 
operating_mode, echo_flag) 
GSLCM _ (workstation_id, device_number, operating_mode, echo) 
gsetlocmode _ (workstation_id, device_number ,operating_mode, 
echo) 
Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 
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device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


operating_mode 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the operating mode specifying the method of input. This 
argument can be any of the following values, according to the ANSI GKS 
standard: 


Value Constant Description 

0 = GKS$K_INPUT_MODE_ Request mode 
REQUEST 

1 GKS$K_INPUT_MODE_SAMPLE Sample mode 

2 GKS$K_INPUT_MODE_EVENT Event mode 

echo_flag 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the echo flag. This flag determines whether or not the 
prompt and input values are echoed on the workstation surface. This 
argument can be either of the following values or constants: 


Value Constant Description 
0 GKS$K_NOECHO Disable the echo. 
1 GKS$K_ECHO Enable the echo. 
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20 


25 


38 


140 


Completion 
Status Code 


DECGKS$_ERROR_NEG_16 
DECGKS$_ERROR_NEG_ 20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 


GKS$_ERROR_140 


Message 


Echo switch is invalid in routine 
EEK 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


_ Specified workstation is neither of 


category INPUT nor of category 
OUTIN in routine **** 


Specified input device is not 
present on workstation in routine 


RR 


To see an example of a call to this function, refer to Example 7-1. 
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SET PICK MODE 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SET PICK MODE establishes the operating mode of a pick 
logical input device, and determines whether DEC GKS echoes the prompt 
and input values on the workstation surface. 


Syntax 
GKS$SET_PICK_MODE  (worksiation_id, device_number, 
operating_mode, echo_flag) 
GSPKM _  (workstation_id, device_number, operating_mede, echo) 
gsetpickmode (workstation_id, device_number ,operating_mode, 
echo) 
Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 
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device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. To see if your workstation 
supports more than one logical device type, refer to the DEC GKS Device 
Specifics Reference Manual. 


operating mode 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the operating mode specifying the method of input. This 
argument could be any of the following values, according to the ANSI GKS 
standard: 


Value Constant Description 
0 GKS$K_INPUT_MODE_REQUEST Request mode 
1 GKS$K_INPUT_MODE_SAMPLE Sample mode 
2 GKS$K_INPUT_MODE_EVENT Event mode 
echo_flag 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the echo flag. This flag determines whether or not the 
prompt and input values are echoed on the workstation surface. This 
argument can be either of the following values or constants: 


Value Constant Description 
0 GKS$K_NOECHO Disable the echo. 


1 GKS$K_ECHO Enable the echo. 
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SET PICK MODE 
Error Messages 
Error Completion 
Number Status Code Message 
-16 DECGKS$_ERROR_NEG_16 Echo switch is invalid in routine 
REE 
—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 
7 GKS$_ERROR_7 GKS not in proper state; GKS 
shall be in one of the states WSOP, 
; WSAC, or SGOP in routine **** 
20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 
25 GKS$_ERROR_25 Specified workstation is not open 
in routine **** 
38 GKS$_ERROR_38 Specified workstation is neither of 


category INPUT nor of category 
OUTIN in routine **** 


140 GKS$_ERROR_140 Specified input device is not 


present on workstation in routine 
RK 


Program Example 


To see an example of a call to this function, refer to Example 7-7. 
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SET STRING MODE 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SET STRING MODE establishes the operating mode of a string 
logical input device, and specifies whether DEC GKS echoes the prompt and 
input values on the workstation surface. 


Syntax 


GKS$SET_STRING_MODE  (worksiation_id, device_number, 
operating_mode, echo_flag) 
GSSTM _ (workstation_id, device_number, operating_mode, echo) 


gsetstringmode (workstation_id, device_number, 
operating_mode, echo) 


Arguments 


workstation_id 


data type: integer 

access: read-only 

mechanism: by reference 

This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 
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device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


operating _mode 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the operating mode specifying the method of input. This 
argument could be any of the following values, according to the ANSI GKS 
standard: 


Value Constant Description 
0 GKS$K_INPUT_MODE_REQUEST Request mode 
1 GKS$K_INPUT_MODE_SAMPLE Sample mode 
2 GKS$K_INPUT_MODE_EVENT Event mode 
echo_flag 

data type: integer 

access: ‘read-only 

mechanism: by reference 


This argument is the echo flag. This flag determines whether or not the 
prompt and input values are echoed on the workstation surface. This 
argument can be either of the following values or constants: 


Value Constant Description 
0 GKS$K_NOECHO Disable the echo. 
1 GKS$K_ECHO Enable the echo. 
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SET STRING MODE 


Error Messages 


Program Example 
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Error 
Number 


20 


25 


38 


140 


Completion 
Status Code 


DECGKS$_ERROR_NEG_16 
DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 


GKS$_ERROR_140 


Message 


Echo switch is invalid in routine 
KKK 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Specified input device is not 


present on workstation in routine 
RA 


To see an example of a call to this function, refer to Example 7-8. 
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SET STROKE MODE 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SET STROKE MODE establishes the operating mode of a 
stroke logical input device, and determines whether DEC GKS echoes the 
prompt and input values on the workstation surface. 


Syntax 
GKS$SET_STROKE_MODE § (workstation_id, device_number, 
operating_mode, echo_flag) 
GSSKM_ (workstation_id, device_number, operating_mode, echo) 
gsetstrokemode  (workstation_id, device_number, 
operating_mode, echo) 
Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 
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device_number 


data type: integer 
- access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


operating _mode 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the operating mode specifying the method of input. This 
argument could be any of the following values, according to the ANSI GKS 


standard: 

Value Constant ; Description 
0 GKS$K_INPUT_MODE_REQUEST Request mode 
1 GKS$K_INPUT_MODE_SAMPLE Sample mode 
2 GKS$K_INPUT_MODE_EVENT Event mode 
-echo_flag 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the echo flag. This flag determines whether or not the 
prompt and input values are echoed on the workstation surface. This 
argument can be either of the following values or constants: 


Value Constant Description 
0 GKS$K_NOECHO Disable the echo. 
1 GKS$K_ECHO Enable the echo. 
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Error Messages 


. Error Completion 
Number Status Code 
~16 DECGKS$_ERROR_NEG_16 
—20 DECGKS$_ERROR_NEG_20 
7 GKS$_ERROR_7 
20 GKS$_ERROR_20 
25 GKS$_ERROR_25 
38 GKS$_ERROR_38 
140 GKS$_ERROR_140 


Program Example 


SET STROKE MODE 


Message 


Echo switch is invalid in routine 
KKK 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Specified input device is not 


present on workstation in routine 
eK 


To see an example of a call to this function, refer to Example 7-9. 
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SET VALUATOR MODE 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SET VALUATOR MODE establishes the operating mode of a 
valuator logical input device, and determines whether DEC GKS echoes the 
prompt and input values on the workstation surface. 


Syntax 
GKS$SET_VALUATOR_MODE § (worksiation_id, device_number, 
operating_mode, echo_flag) 
GSVLM_ (workstation_id, device_number, operating_mode, echo) 
gsetvalmode (workstation_id, device_number, operating_mode, 
echo) 
Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 
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device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


operating _mode 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the operating mode specifying the method of input. This 
argument could be any of the following values, according to the ANSI GKS 
standard: 


Value Constant Description 
0 GKS$K_INPUT_MODE_REQUEST Request mode 
1 GKS$K_INPUT_MODE_SAMPLE Sample mode 
2 GKS$K_INPUT_MODE_EVENT Event mode 
echo_flag 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the echo flag. This flag determines whether or not the 
prompt and input values are echoed on the workstation surface. This 
argument can be either of the following values or constants: 


Value Constant Description 
0 GKS$K_NOECHO Disable the echo. 
1 GKS$K_ECHO Enable the echo. 
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20 


25 


38 


140 


Completion 
Status Code 


DECGKS$_ERROR_NEG_16 


DECGKS$_ERROR_NEG_20 | 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 


GKS$_ERROR_140 


Message 


Echo switch is invalid in routine 
KEK 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Specified input device is not 


present on workstation in routine 
RRR 


To see an example of a call to this function, refer to Example 7-10. 
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Requesting Input 


This section describes the functions used to initiate the request for input 
from a logical input device. With DEC GKS, the default input operating 
mode is request mode. See Section 7.5 for information concerning the 
different types of input operating modes. 


This section describes the following functions: 


REQUEST CHOICE 
REQUEST LOCATOR 
REQUEST PICK 
REQUEST STRING 
REQUEST STROKE 
REQUEST VALUATOR 
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REQUEST CHOICE 


Operating. States: WSOP, WSAC, SGOP 


Description 


The function REQUEST CHOICE prompts the user for input according to 
the specifications you may have passed to INITIALIZE CHOICE and SET 
CHOICE MODE. At this point in the application program, the user makes 
a selection from several possibilities (for example, by moving the cursor 
through a menu) and then signals whether or not the input is valid. 


If the user accepts the input, the function writes GKS$K_STATUS_OK to 
the status argument, and the positive integer representing the user’s choice 
to the input argument. 


If the user invokes a break action, the function returns GKS$K_STATUS_ | 
NONE to the status argument, and the value 0 to the input argument. For 
choice class logical input devices, the value 0 indicates a break; the status 
GKS$K_STATUS_OK indicates input; and the status GKS$K_STATUS_ 
NOCHOICE indicates that the user did not make a choice (input was 
triggered without the cursor being moved). 


Syntax 


GKS$REQUEST CHOICE (workstation_id, device_number, 
input_status, choice_value) 

GRQCH_  (workstation_id, device_number, in_status, ch_num) 

greqchoice (workstation_id, device_number, response) 
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REQUEST CHOICE 

Arguments 

workstation_id 

data type: integer 

access: read-only 

mechanism: by reference 

This argument is the workstation identifier specified in a previous call to 

OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


input_status 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the status of the input 
process. This argument can be any of the following values or constants: 


Value Constant Description 

0 GKS$K_STATUS_NONE Input break. 

1 GKS$K_STATUS_OK Input obtained. 

2 GKS$K_STATUS_NOCHOICE _ Triggered without choosing. 


choice_value 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the integer representing the 
user’s choice. 
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20 
25 


38 


140 


141 


Completion 
Status Code 
DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 
GKS$_ERROR_140 


GKS$_ERROR_141 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state; GKS | 
shall be in one of the states WSOP, 
WSAC, or SGOP 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Specified input device is not 


present on workstation in routine 
sea 


Input device is not in REQUEST 
mode in routine **** 


To see an example of a call to this function, refer to Example 7-6. 
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REQUEST LOCATOR 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function REQUEST LOCATOR prompts the user for input according 
to the specifications you may have passed to INITIALIZE LOCATOR and 
SET LOCATOR MODE. At this point in the application program, the user 
positions the cursor within the echo area, indicating a device coordinate 
corresponding to a world coordinate point, and then signals whether or not 
the input is valid. 


For more information about the locator position and echo types 2 and 3, 
see Chapter 1, VAXstation Workstation Specifics, in the DEC GKS Device 
Specifics Reference Manual. 


If the user accepts the input, the function writes GKS$K_STATUS_OK to 
the status argument and writes the information about the input point to the 
last three arguments. One argument contains the transformation number 
used to transform the device coordinate to a world coordinate point. The 
remaining arguments contain the corresponding world coordinate points. 


If the user invokes a break action, the function writes GKS$K_STATUS_ 
NONE to the status argument. DEC GKS ignores the current input values 
of the locator class device if the user invokes a break action. 


GKS$REQUEST_LOCATOR § (workstation_id, 
device_number, input_status, 
transformation_number, world_x, 
world_y) 
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GRQLC_ (worksiation_id, device_number, in_status, xform, pos_x, 
pos_y) | 
greqloc (workstation_id, device_number, response) 


Arguments 
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workstation_id 

data type: integer 
access: read-only 
mechanism: by reference 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


input_status 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the status of the input 
process. This argument can be either of the following values or constants: 


Value Constant Description 

0 GKS$K_STATUS_ No input obtained. 
NONE 

1 GKS$K_STATUS_OK Input obtained. 
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transformation_number 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the number of the 
normalization transformation used to translate the input point to a world 
coordinate point. 


world_x 

world_y 

data type: real 

access: write-only 
mechanism: by reference 


These are the arguments to which DEC GKS writes the X and Y world 
coordinate values. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state, GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 

20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 

25 GKS$_ERROR_25 Specified workstation is not open 


in routine **** 
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Error Completion 
Number Status Code 


38 GKS$_ERROR. 38 
140 GKS$_ERROR_140 
141 GKS$_ERROR_141 


Program Example 


Message 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Specified input device is not 


present on workstation in routine 
KK 


Input device is not in REQUEST 
mode in routine **** 


To see an example of a call to this function, refer to Example 7-1. 
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REQUEST PICK 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function REQUEST PICK prompts the user for input according to the 
specifications you may have passed to INITIALIZE PICK and SET PICK 


MODE. At this point in the application program, the user positions a cursor 


on a portion of a segment and then signals whether or not the input is valid. 


If the user accepts the input, the function writes GKS$K_STATUS_OK 

to the status argument, and writes the integers representing the name 

of the chosen segment and the chosen pick identifier (refer to SET PICK 
IDENTIFIER in Chapter 8, Segment Functions) to the last two arguments. 


If the user invokes a break action, the function returns GKS$K_STATUS_ 
NONE to the status argument, and the input values are invalid. If the 
user triggered the input measure before moving the prompt, or if the user 
triggers input while the cursor is not positioned on a segment, then this 
function writes GKS$K_STATUS_NOPICK to the status argument. 


GKS$REQUEST_PICK (workstation_id, device_number, 
input_status, segment_name, pick_id) 


GRQPK_ = (workstation_id, device_number, in_status, 
segment_name, pick_id) 
greqpick (workstation_id, device_number, response) 
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REQUEST PICK 
Arguments 
_ workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 
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This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


input_status 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the status of the input 
process. This argument can be any of the following values or constants: 


Value Constant Description 

0 GKS$K_STATUS_NONE Break during input. 

1 GKS$K_STATUS_OK Input obtained. 

2 GKS$K_STATUS_NOPICK Input triggered without picking. 


segment_name 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the integer representing the 
chosen segment. 
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pick_id 


data type: 
access: 


mechanism: 


integer 
write-only 
by reference 


Requesting Input 
REQUEST PICK 


This is the argument to which DEC GKS writes the integer pick identifier 
value associated with the picked primitive within the segment. 


Error Messages 


20 
25 
37 


140 


141 


Program Example 


Completion 
Status Code | 


DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_37 


GKS$_ERROR_140 


GKS$_ERROR_141 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 

Specified workstation is not open 
in routine **** 

Specified workstation is not of 
category OUTIN in routine **** 
Specified input device is not 
present on workstation in routine 
ote ofc ofe age : 

Input device is not in REQUEST 
mode in routine **** 


For an example of a call to this function, refer to Example 7-7. 
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REQUEST STRING 


Operating States: WSOP, WSAC, SGOP 
Description 


The function REQUEST STRING prompts the user for input according to 
the specifications you may have passed to INITIALIZE STRING and SET 
STRING MODE. At this point in the application program, the user enters a 
string of characters.at the prompt and then signals whether or not the input 
is valid. 


When requesting string input, the following two buffers exist: 


¢ The application’s string buffer, whose size you specify when you pass the 
buffer argument by descriptor to REQUEST STRING. 


¢ The logical input device’s string buffer, whose size you can specify in the 
call to INITIALIZE STRING. 


If the user accepts the input, the function writes GKS$K_STATUS_OK to 
the status argument, the character string to the application’s buffer, and the 
length of the character string to the last argument. If the entered string is 

_ larger than the application’s buffer, then you lose all additional data. You 
must make sure that your application’s buffer is as large as the device’s 
string buffer. 


If the user invokes a break action, the function returns GKS$K_STATUS_ 
NONE to the status argument, and the input arguments are not valid. 


Syntax 


GKS$REQUEST_STRING (workstation_id, device_number, 
input_status, string_buffer, string_size) 


GRQST _(workstation_id, device_number, in_status, num_char, 
cstring) 


7-134 Input Functions 


Requesting Input 
REQUEST STRING 


GRQST - Subset (worksiation_id, device_number, in_status, 
num_char, cstring) 


greqstring (workstation_id, device_number, response) 


Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 
This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. To see if your workstation 
supports more than one logical device type, refer to the DEC GKS Device 
Specifics Reference Manual. 


input_status 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the status of the input 
process. This argument can be either of the following values or constants: 


Value Constant Description 

0 GKS$K_STATUS_ No input obtained. 
NONE 

1 GKS$K_STATUS_OK Input obtained. 
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string_buffer | 
data type: string 
access: write-only 
mechanism: by descriptor, data type in descriptor 


This is the argument to which DEC GKS writes the input character string. 
This is the application’s string buffer. . 


string_size 


data type: _ integer 
access: write-only 
mechanism: by reference 
_ This is the argument to which DEC GKS writes the size of the character 
string, in bytes. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 _ GKS not in proper state; GKS 

shall be in one of the states WSOP, 

WSAC, or SGOP in routine **** 

20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 

25 GKS$_ERROR_25 Specified workstation is not open 


in routine **** 
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Error 
Number 


38 


140 


141 


Program Example 


Completion 
Status Code 


GKS$_ERROR_38 


GKS$_ERROR_140 


GKS$_ERROR_141 


Requesting Input 
REQUEST STRING 


Message 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Specified input device is not 


present on workstation in routine 
RR 


Input device is not in REQUEST 
mode in routine **** 


To see an example of a call to this function, refer to Example 7-8. 
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REQUEST STROKE 


Operating States: WSOP, WSAC, SGOP 
Description 


The function REQUEST STROKE prompts the user for input according 
to the specifications you may have passed to INITIALIZE STROKE and 
SET STROKE MODE. At this point in the application program, the user 
designates certain points to be contained in the stroke and then signals 
whether or not the input is valid. 


If the user accepts the input, the function writes GKS$K_STATUS_OK to 
the status argument, and writes the normalization transformation number 
used to translate the device coordinates to world coordinate points, the 
returned stroke points, the number of entered points, and the number of 
accepted points to the corresponding output arguments. 


When requesting stroke input, the following two buffers exist: 
e The application’s stroke buffer, whose size you specify when you pass the 
buffer argument by descriptor to REQUEST STROKE. 


¢ The logical input device’s stroke buffer, whose size you can specify in the 
call to INITIALIZE STROKE. 


DEC GKS can return points up to the number specified by the size of the 
application’s X and Y coordinate buffers. If the size of the entered stroke is 
larger than the number of points placed in the application’s buffers, you lose 
all additional data. You must make sure that your application’s buffers are 
as large as the device’s stroke buffers. 


If the user invokes a break action, the function returns GKS$K_STATUS_ 
NONE to the status argument, and the input values are not valid. 
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Syntax 


Requesting Input 
REQUEST STROKE 


GKS$REQUEST . SIGOKE (workstation_id, device_number, 
input_status, transformation_number, 
num_entered_points, 
stroke_buffer_x, stroke_buffer_y, 
stroke_size_x, stroke_size_y) 


GRQSK_ = (worksiation_id, device_number, max_pts, in_status, 
Xform, num_pts, Px, py) 


greqstroke (workstation_id, device_number, response) 


Arguments 


workstation_id 


data type: . integer 

access: read-only 

mechanism: by reference 

This argument is the workstation identifier spesitied in a previous call to 
OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


input_status 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the status of the input 
process. This argument can be either of the following values or constants. 
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REQUEST STROKE 
Value Constant Description 
0 GKS$K_STATUS_NONE No input obtained. 
1 GKS$K_STATUS_OK Input obtained. 
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transformation_number 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the number of the 
normalization transformation used to translate the input points to world 
coordinate points. 


num_entered_points 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the number of points in the 
stroke entered by the user. 


stroke_buffer_x 
stroke _buffer_y 


data type: array (real) 
access: write-only 
mechanism: by reference 


These are the arguments to which DEC GKS writes the X and Y world coor- 
dinate values of the accepted stroke. These arguments are the application’s 
stroke buffer. 


stroke_size_x 
stroke_size_y 


data type: integer 
access: write-only 
mechanism: by reference 


These are the arguments to which DEC GKS writes the number of stroke 
points that DEC GKS actually accepted. 
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20 
25 


38 
140 


141 


Program Example 


Completion 
Status Code 


DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 


GKS$_ERROR_140 


GKS$_ERROR_141 


Requesting Input 
REQUEST STROKE 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Specified input device is not 
present on workstation in routine 
RK 

Input device is not in REQUEST 
mode in routine **** 


For an example of a call to this function, refer to Example 7-9. 
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REQUEST VALUATOR 


Operating States: WSOP, WSAC, SGOP 


Description 


The function REQUEST VALUATOR prompts the user for input according 
to the specifications you may have passed to INITIALIZE VALUATOR and 
SET VALUATOR MODE. At this point in the application program, the user 
selects a value within a defined range and then signals whether or not the 
input is valid. 


If the user accepts the input, the function writes GKS$K_STATUS_OK to 
the status argument, and the selected real number to the input argument. 


If the user invokes a break action, the function returns GKS$K_STATUS_ 
NONE to the status argument, and the input value is not valid. 


Syntax 
GKS$REQUEST_VALUATOR § (worksiation_id, device_number, 
input_status, real_value) 
GRQVL_ (workstation_id, device_number, in_status, value) 
greqval (workstation_id, device_number, response) 
Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. | 
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device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


input_status 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the status of the input 
process. This argument can be either of the following values or constants: 


Value Constant Description 

0 GKS$K_STATUS_ No input obtained. 
NONE 

1 GKS$K_STATUS_OK Input obtained. 

real_value 

data type: real 

access: write-only 

mechanism: by reference 


This is the argument to which DEC GKS writes the real number chosen by 
the user. 
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20 


25 


38 


140 


141 


Completion 
Status Code 
DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 
GKS$_ERROR_140 


GKS$_ERROR_141 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state; GKS 


shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


_ Specified workstation identifier is 


invalid in routine **** 
Specified workstation is not open 
in routine **** 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Specified input device is not 
present on workstation in routine 
he 


Input device is not in REQUEST 
mode in routine **** 


For an example of a call to this function, refer to Example 7-10. 
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Sampling Input 


Sampling Input 


This section describes the functions used to sample the current measure of 
a logical input device. DEC GKS returns the measure of the device without 
requiring a trigger from the user. See Section 7.5 for information concerning 
the different types of input operating modes. 


This section describes the following functions: 


SAMPLE CHOICE 
SAMPLE LOCATOR 
SAMPLE PICK 
SAMPLE STRING 
SAMPLE STROKE 
SAMPLE VALUATOR 


Input Functions 7—145 


Sampling Input 
SAMPLE CHOICE 


SAMPLE CHOICE 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SAMPLE CHOICE writes the current measure of the specified 
choice logical input device to the corresponding output argument. 


If the input is valid, the function writes GKS$K_STATUS_OK to the status 
argument and writes the positive integer representing the user’s choice to 
the input argument. 


If the initial choice status is GKS$K_STATUS_NOCHOICE, and if the 
user did not move the prompt from its initial position, this function writes 
GKS$K_STATUS_NOCHOICE to the status argument (this indicates that 
the user did not make a choice yet). 


Syntax 
GKS$SAMPLE_CHOICE (workstation_id, device_number, 
input_status, choice_value) 
GSMCH (workstation_id, device_number, in_status, ch_num) 
gsamplechoice (workstation_id, device_number, response) 
Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 
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device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


input_status 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the status of the input 
process. This argument can be either of the following values or constants: 


Value Constant Description 
1 GKS$K_STATUS_OK Input obtained. 
2 GKS$K_STATUS_NOCHOICE Sampled without choosing. 


* 


choice_value 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the integer representing the 
user’s choice. 
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Error 
Number 


—20 


20 
25 


38 
140 


142 


Program Example 


Completion 
Status Code 


DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 
GKS$_ERROR_140 


GKS$_ERROR_142 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Specified input device is not 


present on workstation in routine 
Kee 


Input device is not in SAMPLE 
mode in routine **** 


Example 7-11 illustrates the use of the function SAMPLE CHOICE. 
Following the program example, Figures 7-18 through 7-20 illustrate the 


program’s effect on a VT241 workstation. 
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Example 7-11: Using a Choice Logical Input Device in Sample Mode 





Cc 


aaa 


qaaa 


This program initializes and Samples choice input from a VT241. 
IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, DATA _RECORD( 3 ), NUM_CHOICES, SIZES( 3 ), 
* ADDRESSES ( 3 ), PROMPT_ECHO TYPE, ERROR_STATUS, 

* INPUT MODE, ECHO FLAG, RECORD BUFFER_LENGTH, RECORD SIZE, 
* INPUT _ STATUS, INITIAL CHOICE, DEVICE_NUM, INPUT_CHOICE, 

* INITIAL STATUS, NUM_POINTS, COLOR1, COLOR2, COLOR3 

REAL ECHO AREA( 4 ), PX( 4 ), PY( 4 ), LARGER 

DATA PX / 0.05, 0.1, 0.075, 0.05 / 

DATA PY / 0.85, 0.85, 0.80, 0.85 / 

DATA NUM_POINTS / 4 /, COLOR1 / 1 /, COLOR2 / 2 /, 

* COLOR3 / 3 /, LARGER / 0.03 / 


CHARACTER*80 CURRENT _STRINGS( 3 ) 
DATA WS_ID / 1 /, DEVICE_NUM / 1 / 


First element in the data record is the number of choices. 
EQUIVALENCE ( DATA_RECORD(1), NUM_CHOICES ) 

CALL GKSSOPEN_GKS( ‘SYSS$ERROR:’ ) 

CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSS$ACTIVATE_WS( WS_ID ) 


Establish the size of the record buffer: 12 bytes. 
RECORD _BUFFER_LENGTH = 12 


The second element in the VT241 choice data record is the pointer to 
the array containing sizes of each choice character string. You need 
to initialize the pointer so that the array can be initialized. 
DATA_RECORD( 2 ) = %LOC( SIZES(1) ) 


The third element in the VT241 choice data record is the pointer to the 
array containing the pointers to the strings to be used. You need 
to initialize the pointer so that the array can be initialized. 


DATA_RECORD( 3 ) = %LOC( ADDRESSES(1) ) 

ADDRESSES( 1 ) = *LOC( CURRENT STRINGS( 1 ) ) 

ADDRESSES ( 2 ) = %LOC( CURRENT _STRINGS( 2 ) ) 
3)) 


ADDRESSES ( 3 ) = %LOC( CURRENT STRINGS ( 


Inquire about the current values. 

NUM_CHOICES = 3 

CALL GKS$INQ_ CHOICE STATE ( WS_ID, DEVICE_NUM, 

* ERROR_STATUS, INPUT_MODE, ECHO FLAG, INITIAL STATUS, 
* INITIAL CHOICE, PROMPT ECHO TYPE, ECHO AREA, 

* DATA RECORD, RECORD_BUFFER_LENGTH, RECORD SIZE ) 





(continued on next page) 
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Cc Set the initial choice status. 
INITIAL STATUS = GKS$K_STATUS_OK 


Cc Establish sizes of prompt strings... 
SIZES( 1) = 4 
SIZES( 2) = 5 
SIZES( 3) = 4 

Cc Establish locations of prompt strings... 


SLOC( '’Pink’ ) 
‘$LOC( ‘Green’ ) 
$LOC( ’Blue’ ) 


ADDRESSES ( 1 ) 
ADDRESSES ( 2 ) 
ADDRESSES ( 3 ) 


Cc To initialize a device, make sure it’s in request mode (the DEC 
Cc GKS default). 

CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 

* GKS$K_INPUT_MODE_ REQUEST, GKS$K_ECHO ) 


CALL GKS$INIT_CHOICE( WS_ID, DEVICE_NUM, 
* INITIAL STATUS, INITIAL CHOICE, PROMPT ECHO TYPE, 
* ECHO_AREA, DATA _RECORD, RECORD _BUFFER_LENGTH ) 


1] CALL GKS$SET_CHOICE_MODE ( WS_ID, DEVICE _NUM, 

* GKS$K_INPUT_MODE SAMPLE, GKS$K_ECHO ) 
Cc Initialize color indexes. 

CALL GKS$SET_COLOR_REP ( WS_ID, COLORI1, 0.6258, 0.2142, 
* 0.2142 ) 
CALL GKS$SET_COLOR_REP ( WS_ID, COLOR2, 0.1400, 1.000, 
* 0.1400 ) 
CALL GKSSSET_COLOR_REP ( WS_ID, COLOR3, 0.0, 0.0, 
* 0.8400 ) 


CALL GKS$SET_FILL_COLOR_INDEX( COLOR1 ) 
CALL GKS$SET FILL INT STYLE( GKS$K_INTSTYLE SOLID ) 





(continued on next page) 
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Cc Tell the user how to change colors. 
CALL GKS$SET_TEXT HEIGHT( LARGER ) 
CALL GKS$TEXT( 0.05, 0.95, ’Move the arrow keys to’) 
CALL GKS$TEXT( 0.05, 0.90, ‘change the triangle colors.’) 


Cc Do until the surface is full. 
DO WHILE ( PX( 2 ) .LT. 0.95 ) 


CALL GKS$SAMPLE_CHOICE( WS_ID, DEVICE_NUM, 
* INPUT STATUS, INPUT_CHOICE ) 


Cc Depending on the sample, change the color. 
IF ( INPUT CHOICE .EQ. 1 ) THEN 
CALL GKS$SET_FILL_COLOR_INDEX( COLORI1 ) 
ENDIF 
IF ( INPUT_CHOICE .EQ. 2 ) THEN 
CALL GKS$SET_FILL COLOR_INDEX( COLOR2 ) 
ENDIF 
IF ( INPUT_CHOICE .EQ. 3 ) THEN 
CALL GKS$SET_FILL_ COLOR_INDEX( COLOR3 ) 
ENDIF 


CALL GKS$FILL_AREA( NUM_POINTS, PX, PY ) 


PY( 1) = P¥( 1) - 0.06 
PY( 2) = PY¥( 2) - 0.06 
PY¥( 3) = PY¥( 3) - 0.06 
PY( 4) = PY( 4) - 0.06 
IF ( PY( 2-) .LT. 0.05 ) THEN 
PY( 1) = 0.85 
PY( 2) = 0.85 
PY( 3 ) = 0.80 
PY( 4) = 0.85 
PX( 1) = PX( 1) + 0.06 
PX( 2) = PX( 2 ) + 0.06 
PX( 3) = PX( 3) + 0.06 
PX( 4) = PX( 4 ) + 0.06 
ENDIF 
ENDDO 
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Cc Turn off the sample prompt. 
4] CALL GKS$SET_CHOICE_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_REQUEST, GKS$K_ECHO ) 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ The call to SET CHOICE MODE sets the input operating mode to 
sample. At this point in the program, the choice prompt appears on the 
workstation surface and the user can change the measure of the device. 


@ This call to SAMPLE CHOICE retrieves the current input value (without 
the user having to trigger the device). The WHILE loop ends when the 
program fills the workstation surface with triangles. 


© This code draws triangles in columns. 


@ The call to SET CHOICE MODE returns the logical input device to 
request mode. At this point, the device handler removes the choice 
prompt from the workstation surface and the user can no longer enter 
input. 


Figure 7-18 illustrates the surface of the VT241 when the input mode is 
set. Figure 7-19 illustrates the surface of the VT241 when the user moves 
the prompt to the second choice. Notice that the user need only move the 
prompt to another color (without triggering) and the color of the triangles 
change accordingly. Figure 7~20 illustrates the surface of the VT241 when 
the workstation surface is full. 
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Figure 7-18: The Choice Logical Input Device in Sample Mode—VT241 
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Figure 7-19: The Choice Logical Input Device in Sample Mode—VT241 
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Figure 7-20: The Choice Logical Input Device in Sample Mode—VT241 
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SAMPLE LOCATOR 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SAMPLE LOCATOR writes the current measure of the 
specified device and the corresponding normalization transformation number 
to the appropriate output arguments. 


Syntax 
GKS$SAMPLE_LOCATOR = (workstation_id, device_number, 
transformation_number, world_x, 
world_y) | 
GSMLC_ (workstation_id, device_number, xform, pos_x, pos_y) 
gsampleloc (workstation_id, device_number, response) 
Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 
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device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


transformation_number 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the normalization trans- 
formation number used to translate the input point to a world coordinate 


point. 

world_x 

world_y 

data type: real 

access: write-only 
mechanism: by reference 


These are the arguments to which DEC GKS writes the X and Y world 
coordinate values. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP 
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Error. Completion 
Number Status Code Message 
20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 
25 GKS$_ERROR_25 Specified workstation is not open 
in routine **** 
38 GKS$_ERROR_38 Specified workstation is neither of 


category INPUT nor of category 
OUTIN in routine **** 


140 GKS$_ERROR_140 Specified input device is not 


present on workstation in routine 
RE 


142 GKS$_ERROR_142 Input device is not in SAMPLE 
mode in routine **** 


Program Example 


For an example of a call to this function, refer to Example 7-2. 
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SAMPLE PICK 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SAMPLE PICK writes the current measure of the specified 
pick logical input device to the corresponding output argument. 


If the input is valid, the function writes GKS$K_STATUS_OK to the status 
argument and writes the positive integers representing the picked segment 
and the pick identifier to the output arguments. 


If the initial choice status is GKS$K_STATUS_NOPICK, and if the user did 
not move the prompt, this function writes GKS$K_STATUS_NOPICK to the 
status argument (this indicates that the user did not pick a segment yet). 
The logical input device also returns GKS$K_STATUS_NOPICK if the user 
moved the prompt but the aperture is not touching a segment at the time of 
the sample. 


Syntax 


GKS$SAMPLE_PICK (workstation_id, device_number, 
input_status, segment_name, pick_id) 
GSMPK_(workstation_id, device_number, in_status, 
segment_name, pick_id) 
gsamplepick (workstation_id, device_number, response) 
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Arguments. 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


7-160 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


input_status 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the status of the input 
process. This argument can be either of the following values or constants: 


Value Constant Description 
1 GKS$K_STATUS_OK _ Input obtained. 
2 GKS$K_STATUS_NOPICK Sampled without picking. 


segment_name 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the integer een ee the 
chosen segment. 


Input Functions 


pick_id 


data type: 
access: 


mechanism: 


integer 
write-only 
by reference 


Sampling Input 
SAMPLE PICK 


This is the argument to which DEC GKS writes the integer pick identifier 
value associated with the picked primitive within the segment. For more 
information, refer to Chapter 8, Segment Functions. 


Error Messages 


20 
25 
37 


140 


142 


Completion 
Status Code 
DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_37 


GKS$_ERROR_140 


GKS$_ERROR_142 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 
GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP 

Specified workstation identifier is 
invalid in routine **** 

Specified workstation is not open 
in routine **** 


Specified workstation is not of 
category OUTIN in routine **** 


Specified input device is not 


present on workstation in routine 
BRK 


Input device is not in SAMPLE 
mode in routine **** 
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Example 7-12 illustrates the use of the function SAMPLE PICK. Following 
the program example, Figures 7-21 through 7—23 illustrate the program’s 
effect on a VT241 workstation. 


Example 7-12: Using a Pick Logical Input Device in Sample Mode 


C This program initializes and samples pick input from a VT241. 
IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, INITIAL STATUS, SEGMENT, 

PICK_ID, PROMPT ECHO TYPE, ERROR_STATUS, 

INPUT MODE, ECHO ) FLAG, RECORD_BUFFER_LENGTH, 
RECORD SIZE, INPUT STATUS, 

DEVICE NUM, BOX_1, BOX_2, TRIANGLE 1, 

TRIANGLE 2, NUM POINTS 
REAL ECHO . ) AREA (4), DATA_RECORD( 1 ) 
REAL X_VALUES( 4 ), Y_VALUES( 4 ), LARGER 
DATA WS_ID / 1 /, DEVICE_NUM / 1 /, BOX_1/1 /, 
* BOX _2 FT 2e5 TRIANGLE 1 hs TRIANGLE | 2/21, 
* NUM POINTS / 4 /, LARGER / 0.03 / 

DATA | X_VALUES / 0.1, 0.4, 0.1, 0.1 / 

DATA Y_VALUES / 0.3, 0.6, 0.6, 0.3 / 


+ * + % 


CALL GKSSOPEN_GKS( ‘’SYS$ERROR:’ ) 
CALL GKS$OPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE_WS( WS_ID ) 


 ] CALL GKS$SET_FILL_INT_STYLE( GKS$K_INTSTYLE_SOLID ) 


CALL GKSS$CREATE_SEG( BOX_1 ) 

CALL GKS$SET_PICK_ID( TRIANGLE_1 ) 

CALL GKS$SET_FILL COLOR_INDEX( 2 ) 

CALL GKS$FILL_AREA( NUM POINTS, X_VALUES, Y_VALUES ) 
X_VALUES( 3 ) = 0.4 

Y_VALUES( 3 ) = 0.3 

CALL GKS$SET_PICK_ID( TRIANGLE 2 ) 

CALL GKS$SET_FILL_COLOR_INDEX( 3 ) 

CALL GKS$FILL_AREA( NUM_POINTS, X_VALUES, Y_VALUES ) 
CALL GKS$CLOSE_SEG () 
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X_VALUES( 1 ) = 0.6 
X_VALUES( 2 ) = 0.9 
X_VALUES( 3 ) = 0.6 
X_VALUES( 4 ) = 0.6 
Y_VALUES( 3 ) = 0.6 


CALL GKS$SET_PICK_ID( TRIANGLE_1 ) 


CALL GKS$CREATE_SEG( BOX 2 ) 

CALL GKS$SET_FILL COLOR_INDEX( 2 ) 

CALL GKS$FILL_AREA( NUM POINTS, X_VALUES, Y_VALUES ) 
X_VALUES( 3 ) = 0.9 

Y_VALUES( 3 ) = 0.3 

CALL GKS$SET_PICK_ID( TRIANGLE 2 ) 

CALL GKS$SET_FILL COLOR_INDEX( 3 ) 

CALL GKS$FILL_AREA( NUM POINTS, X VALUES, Y_VALUES ) 
CALL GKS$CLOSE_SEG () 


CALL GKS$SET_SEG DETECTABILITY ( BOX_1, GKS$K_DETECTABLE ) 
CALL GKS$SET_SEG DETECTABILITY ( BOX_2, GKS$K_DETECTABLE ) 


CALL GKS$SET_TEXT HEIGHT( 0.03 ) 
CALL GKSS$TEXT( 0.2, 0.45, '1°) 
CALL GKSS$TEXT( 0.3, 0.45, ’2') 
CALL GKS$TEXT( 0.7, 0.45, ’1’) 
CALL GKSS$TEXT( 0.8, 0.45, '2’) 


Cc Declare a data length of one long word which will hold the 
Cc size of the pick prompt. 

RECORD_BUFFER_LENGTH = 4 

CALL GKSS$INQ_PICK_STATE( WS_ID, DEVICE_NUM, 

* GKSS$K_VALUE_REALIZED, ERROR_STATUS, INPUT_MODE, 

* ECHO FLAG, INITIAL STATUS, SEGMENT, PICK_ID, 

* PROMPT ECHO TYPE, ECHO AREA, DATA RECORD, 

* RECORD _BUFFER_LENGTH, RECORD SIZE ) 


Cc Establish initial values. 
SEGMENT = BOX_1 
PICK_ID = TRIANGLE 1 
INITIAL_STATUS = GKSSK_STATUS_OK 


Cc To initialize a device, make sure it’s in request mode (the DEC 
Cc GKS default). 

CALL GKSSSET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 

* GKS$K_INPUT_MODE_ REQUEST t GKS$K_ECHO ) 


CALL GKSSINIT_PICK( WS_ID, DEVICE_NUM, INITIAL_STATUS, 
* SEGMENT, PICK_ID, PROMPT ECHO TYPE, ECHO_AREA, 
* DATA RECORD, RECORD BUFFER_LENGTH ) 


(continued on next page) 


Input Functions. 7-163 


Sampling Input 
SAMPLE PICK 


Example 7-12 (Cont.): Using a Pick Logical Input Device in Sample Mode 


Qe. CALL GKS$SET_PICK_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE SAMPLE, GKS$K_ECHO ) 


Cc Tell the user the task. 
CALL GKS$SET_TEXT_HEIGHT ( LARGER ) 
CALL GKSSTEXT( 0.05, 0.95, ‘Move the cursor to a triangle.’ ) 
CALL GKSSTEXT( 0.05, 0.90, ’I will say if it is correct.’) 


Cc Do until the user picks the second triangle in the second box. 
DO WHILE (( SEGMENT .NE. 2 ) .OR. ( PICK_ID .NE. 2 )) 
© CALL GKS$SAMPLE_PICK( WS_ID, DEVICE_NUM, INPUT_STATUS, 
* SEGMENT, PICK_ID ) 
Cc Tease the user as s/he gets closer. 
4) IF (( SEGMENT .EQ. 1 ) .AND. ( PICK_ID .EQ. 1 )) THEN 
CALL GKSSTEXT( 0.05, 0.85, 
* ‘You are pretty far away.’) 
ENDIF 


IF (( SEGMENT .EQ. 1 ) .AND. ( PICK_ID .EQ. 2 )) THEN 
CALL GKSS$STEXT( 0.05, 0.80, 
7 ‘You are getting closer.’) 
ENDIF 
IF (( SEGMENT .EQ. 2 ) .AND. ( PICK_ID .EQ. 1 )) THEN 
CALL GKSSTEXT( 0.05, 0.75, 
. ‘You are REALLY close.’ ) 
ENDIF 
ENDDO 


CALL GKS$TEXT( 0.05, 0.70, ‘YOU MADE IT!!!’) 


Cc Turn off the sample prompt. 


5) CALL GKS$SET_PICK_MODE( WS_ID, DEVICE_NUM, 
* GKSS$K_INPUT MODE REQUEST, GKS$K_ECHO ) 


CALL GKS$DEACTIVATE WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS() 

END 


The following numbers correspond to the numbers in the previous example: 


@ This code establishes the same divided boxes that appear in Example 7-7. 


@ The call to SET PICK MODE sets the input operating mode to sam- 
ple. At this point in the program, the pick aperture appears on the 
workstation surface and the user can change the measure of the device. 
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© This call to SAMPLE PICK retrieves the current input value (without 
the user having to trigger the device). The WHILE loop ends when the 
user picks the second triangle in the second box. 


@ This code teases the user, saying how close the aperture is to segment 2, 
pick identifier 2. 


© The call to SET PICK MODE returns the logical input device to request 
mode. At this point, the device handler removes the aperture from the 
workstation surface and the user can no longer enter input. 


Figure 7—21 illustrates the surface of the VT241 when the input mode 

is set. Figure 7—22 illustrates the surface of the VIT241 when the user 
moves the aperture closer to the required segment and pick identifier. 
Notice that the user need only move the aperture to another pick identifier 
(without triggering) and a new message appears on the workstation surface. 
Figure 7—23 illustrates the surface of the VI241 when the user picks the 
correct triangle. 
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Figure 7-21: The Pick Logical input Device in Sample Mode—VT241 


Move the cursor to a triangle, 
Iwill say if it is correct. 





2K -5838-HC 


7-166 Input Functions 


Figure 7-22: 


Sampling Input 
SAMPLE PICK 


The Pick Logical Input Device in Sample Mode—VT241 


Move the cursor to a triangle. 
I will say if it is correct, 


You are pretty far away, 
You are getting closer. 
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Figure 7-23: The Pick Logical Input Device in Sample Mode—VT241 


Move the cursor to a triangle, 
IT will say if it is correct. 
You are pretty far away, 

You are getting closer. 

You are REALLY close, 

YOU MADE IT!!! 
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SAMPLE STRING 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function SAMPLE STRING writes the current measure of the specified 


' string logical input device to the appropriate output arguments. 


When activating string input, the following two buffers exist: 


¢ The application’s string buffer, whose size you specify when you pass the 
buffer argument by descriptor to SAMPLE STRING. 


¢ The logical input device’s string buffer, whose size you can specify in the 
call to INITIALIZE STRING. 


When sampling a string, DEC GKS takes the first characters in the entered 
text string, including any initial prompt, up to the number of characters 
specified by the size of the application’s buffer. If the size of the entered 
string is larger than the number of characters placed in the application’s 
buffer, DEC GKS performs the following tasks: 


¢ Removes the sampled string (the size of the application’s buffer) from 
the device’s buffer. 


¢ Places the sampled string in the application’s buffer. 


e Leaves any remaining characters in the device’s buffer. You need to call 
SAMPLE STRING again to access the remaining characters. 


GKS$SAMPLE_STRING (workstation_id, device_number, 
string_buffer, string_size, 
total_string_size) 


GSMST_ (workstation_id, device_number, num_char, cstring) 
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GSMST - Subset (workstation_id, device_number, num_char, 
cstring) 


gsamplestring (workstation_id, device_number, response) 


Arguments 


7~170 


workstation_id 

data type: integer 
access: read-only 
mechanism: by reference 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 


device_number 


data. type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


string_buffer 


data type: string 
access: write-only 
mechanism: by descriptor 


This is the argument to which DEC GKS writes the input character string. 
This is the application’s buffer. 


string_size 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the number of bytes in the 
string accepted by the input sample. 
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total_string_size 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the total number of 
characters in the device’s buffer, in bytes. If this argument’s value is greater 
than the value of string_size, you may wish to call SAMPLE STRING again 
to obtain the characters remaining in the device’s buffer. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP 

20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 

25 GKS$_ERROR_25 Specified workstation is not open 

in routine **** 

38 GKS$_ERROR_38 Specified workstation is neither of 


category INPUT nor of category 
OUTIN in routine **** 


140 GKS$_ERROR_140 Specified input device is not 


present on workstation in routine 
BKB 


142 GKS$_ERROR_142 Input device is not in SAMPLE 
mode in routine **** 
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Program Example 


7-172 


Example 7-13 illustrates the use of the function SAMPLE STRING. 
Following the program example, Figures 7~24 through 7—27 illustrate the 
program’s effect on a VT241 workstation. 


Example 7-13: Using a String Logical Input Device in Sample Mode 


This program initializes and samples string input from a VT241. 
IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, DATA_RECORD( 2 ), 

PROMPT ECHO TYPE, ERROR_STATUS, BUFFER_LENGTH, 
INPUT_MODE, ECHO_FLAG, RECORD_BUFFER_LENGTH, 

RECORD SIZE, INPUT_STATUS, DEVICE_NUM, STRING SIZE, 
CUR_POSITION, TOTAL STRING SIZE, INCR, INCR2, 

EVENT_FLAG 
REAL*8 TIME 
REAL ECHO _AREA( 4 ), START_X, START_Y, X_VECTOR, Y_VECTOR, 
* LARGER 

CHARACTER*31 INITIAL STRING, STRING BUFFER 

DATA WS_ID / 1 /, DEVICE_NUM / 1 /, LARGER / 0.03 / 


First element in the data record is length of the buffer that 
contains the input string. 

EQUIVALENCE ( DATA_RECORD( 1 ), BUFFER_LENGTH ) 

EQUIVALENCE ( DATA_RECORD( 2 ), CUR_POSITION ) 


+ %  € 


CALL GKSSOPEN_GKS( ‘SYS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240° ) 
CALL GKSSACTIVATE_WS( WS_ID ) 


RECORD _BUFFER_LENGTH = 8 

CALL GKS$INQ_STRING_STATE( WS_ID, DEVICE_NUM, 

* ERROR_STATUS, INPUT MODE, ECHO FLAG, INITIAL STRING, 
* STRING_SIZE, PROMPT ECHO TYPE, ECHO_AREA, DATA_RECORD, 
* RECORD BUFFER_LENGTH, RECORD SIZE ) 


Change the current input values. 


ECHO AREA( 1 ) = 437 
BUFFER_LENGTH = 31 
CUR_POSITION = 1 


(continued on next page) 
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Mode 
Cc To initialize a device, make sure it’s in request mode (the DEC 
Cc GKS default). 


CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 
* GKSS$K_INPUT_MODE REQUEST, GKS$K_ECHO ) 


CALL GKSS$INIT_STRING( WS_ID, DEVICE_NUM, ’ ’, 
* PROMPT ECHO TYPE, ECHO AREA, DATA_RECORD, 
* RECORD BUFFER_LENGTH ) 


Cc Tell the user what is happening. 
CALL GKS$SET_TEXT HEIGHT( LARGER ) 
CALL GKSSTEXT( 0.05, 0.95, ‘Every 20 seconds, type a string.’) 
CALL GKSSTEXT( 0.05, 0.90, ‘I will use them in my design.’) 


CALL GKS$SET_STRING_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_ SAMPLE, GKS$K_ECHO ) 


Cc Set the initial text settings and attributes. 
START_X = 0.05 
START_Y = 0.70. 
X_VECTOR = 0.0 
Y_VECTOR = 1.0 


Cc Obtain an event flag for the timer... 
CALL LIBSGET_EF ( EVENT FLAG ) 


Cc Do for three lines. 
DO 200 INCR = 1, 3, 1 


IF ( INCR .NE. 1 ) THEN 


Cc Give the user a 20-second break. 
CALL SYSSBINTIM( ‘0 :00:20’, TIME ) 
CALL SYS$SETIMR( %VAL( EVENT_FLAG ), -( TIME ),,) 
CALL SYSS$WAITFR( %VAL( EVENT_FLAG ) ) 


Cc Sample the string. 
CALL GKSSSAMPLE_ STRING ( WS_ID, DEVICE_NUM, 
* STRING BUFFER, STRING SIZE, TOTAL STRING SIZE ) 
ELSE 
Cc ‘Provide the first string. 
STRING BUFFER = ‘I will give you the first string.’ 
ENDIF 





_ (continued on next page) 
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Example 7-13 (Cont.): Using a String Logical Input Device in Sample 
Mode 


Cc Create a design with a text string. 
5 ] DO 300 INCR2 = 1, 3, 1 
CALL GKS$SET_TEXT_UPVEC( X_VECTOR, Y_VECTOR ) 
CALL GKSSTEXT( START_X, START_Y, 
* STRING BUFFER ) 
X_VECTOR = X_VECTOR + 0.1 
Y_VECTOR = Y_VECTOR - 0.1 
300 CONTINUE 


Cc Reset variables. 
START Y = START_Y - 0.01 
STRING BUFFER = ’ ’ 


200 CONTINUE 


Cc Free the event flag used for the timer. 
CALL LIBSFREE_EF ( EVENT _ FLAG ) 
Cc Turn off the sample prompt. 
6] CALL GKS$SET_STRING_MODE( WS_ID, DEVICE_NUM, 


* GKS$K_INPUT MODE REQUEST, GKS$K_ECHO ) 


CALL GKS$DEACTIVATE WS( WS_ID ) 
CALL GKSSCLOSE_WS( WS_ID ) 

CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ Changing the value of variable ECHO_AREA( 1 ) widens the echo area 
so that the user can enter a larger string than the one which the default 
area allows. 


@ The call to SET STRING MODE sets the input operating mode to 


sample. At this point in the program, the string prompt appears on the 
workstation surface and the user can change the measure of the device. 


© This code creates a 20-second timer that allows the user to enter and 
alter a character string. For more information concerning these function 
calls, refer to the Introduction to VMS System Routines and to the VMS 
Run-Time Library Routines Reference Manual. 
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© This call to SAMPLE STRING retrieves the current input value (without 
the user having to trigger the device). This loop requires two strings 
from the user. The program provides the first string. 


© This code outputs the strings by adjusting the character-up vector. This 
creates a pinwheel design on the workstation surface. 


© The call to SET STRING MODE returns the logical input device to 
request mode. At this point, the device handler removes the string 
prompt from the workstation surface and the user can no longer enter 
input. 


Figure 7—24 illustrates the surface of the VT241 just after the input mode 
is set. Figure 7-25 illustrates the surface of the VT241 after the user types 
a string (note that if the user presses RETURN, nothing happens—the 
application decides when to sample input). Figure 7-26 illustrates the 
surface of the VT241 after the program accepts the first string. Notice that 
the user need only enter and alter the string (without triggering) and the 
program samples the current string accordingly. Figure 7-27 illustrates the 
surface of the VT241 after the user entered all strings. 
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Figure 7-24: The String Logical Input Device in Sample Mode—VT241 


Every 20 seconds, type a string, 
I will use them in my design. 
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Figure 7-25: The String Logical Input Device in Sample Mode—VT241 


Every 20 seconds, type a string, 
I will use them in my design, 


first string. 
first String, 


Bill Buckner, and Jim Rice,_ 
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Figure 7—26: The String Logical Input Device in Sample Mode—VT241 


Every 20 seconds, type a string. 
I will use them in my dasign, 


Til give rE the first string. 
é h i 
“ey Hise You es String, 


$j 
thst String 


e Pq, 


“ 
As 

% Prog 

“Ms a 
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Figure 7-27: The String Logical Input Device in Sample Mode—VT241 


Every 20 seconds, type a string, 
I will use them in my design, 


first string. 
first String, 


ings 
Strip 
g. 


Men 
Pee, 





ZK-5814-HC 


Input Functions 7-179 


Sampling Input 
SAMPLE STROKE 


SAMPLE STROKE 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SAMPLE STROKE writes the current measure of the specified 
stroke logical input device to the corresponding output arguments. 


When activating stroke input, the following two buffers exist: 


e The application’s stroke buffer, whose size you specify when you pass the 
buffer argument by descriptor to SAMPLE STROKE. 


¢ The logical input device’s stroke buffer, whose size you can specify in the 
call to INITIALIZE STROKE. 


When sampling stroke input, DEC GKS accepts any initial stroke points 
and translates entered points according to the current normalization 
transformation. DEC GKS can accept points up to the number specified by 
the size of the application’s buffer. If the size of the entered stroke is larger 
than the number of stroke points placed in the application’s buffer, DEC 
GKS performs the following tasks: 


¢ Removes the sampled stroke (the size of the application’s buffer) from 
the device’s buffer. 


e Places the sampled stroke in the application’s buffer. 


e Leaves any remaining points in the device’s buffer. You need to call 
SAMPLE STROKE again to access the remaining characters. 
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GKS$SAMPLE STROKE (workstation_id, device_number, 
transformation_number, 
num_entered_points, stroke_buffer_x, 
stroke_buffer_y, stroke_size_x, 
stroke_size_y) 


GSMSK_ (worksiation_id, device_number, max_pts, xform, 
_ num_pts, px, py) 
gsamplestroke (workstation_id, device_number, response) 


Arguments 


workstation_id 


data type: integer 

access: read-only 

mechanism: by reference 

This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. . 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 


transformation_number 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the number of the 
normalization transformation used to translate the input points to world 
coordinate points. 
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num_entered_points 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the total number of points 
in the stroke entered by the user. 


stroke_buffer_x 
stroke_buffer_y 


data type: array (real) 
access: write-only 
mechanism: by descriptor 


These are the arguments to which DEC GKS writes the X and Y world coor- 
dinate values of the accepted stroke. These arguments are the application’s 
stroke buffer. 


stroke_size_x 
stroke_size_y 


data type: integer 
access: write-only 
mechanism: by reference 


These are the arguments to which DEC GKS writes the number of stroke 
points actually accepted in the application buffer. 
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Error Completion 

Number Status Code Message 

~20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state; GKS 


shall be in one of the states WSOP, 
WSAC, or SGOP 
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Error 
Number 


20 


25 


38 


140 


142 


Program Example 


Completion 
Status Code 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 


GKS$_ERROR_140 


GKS$_ERROR_142 
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Message 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Specified input device is not 


present on workstation in routine 
Rake 


Input device is not in SAMPLE 
mode in routine **** 


Example 7-14 illustrates the use of the function SAMPLE STROKE. 
Following the program example, Figures 7-28 through 7-33 illustrate the 


program’s effect on a VT241 workstation. 
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Example 7-14: Using a Stroke Logical Input Device in Sample Mode 





Cc This program initializes and samples stroke input from a VT241. 

IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, DATA_RECORD( 6 ), BUFFER_SIZE, 

* DIMENSION, PROMPT _ECHO TYPE, ERROR_STATUS, 

* TRANSERM, NUM_ENTERED POINTS, INPUT_MODE, ECHO FLAG, 

* RECORD _BUFFER_LENGTH, RECORD SIZE, INPUT STATUS, DEVICE_NUM, 
* I, EDIT_POSITION, ATTS_FLAG, TEXT, INCR, INCR2, EVENT FLAG, 
* RET SIZE BUF( 3 ), RET_SIZE_X, RET SIZE Y 

REAL ECHO AREA( 4 ), STROKE X( 50 ), 
* STROKE _Y( 50 ), X_INT, Y_INT, TIME INT, 
* STROKE BUFFER _X( 3, 50 ), STROKE_BUFFER_Y( 3, 50 ), 
* LARGER 

REAL*8 TIME 

DATA WS_ID / 1 /, DEVICE_NUM / 1 /, TEXT / 1 /, 
* LARGER / 0.03 / 


Cc First element in the data record is the buffer size. 
EQUIVALENCE ( DATA_RECORD( 1 ), BUFFER SIZE) 
EQUIVALENCE ( DATA_RECORD( 2 ), EDIT POSITION) 
EQUIVALENCE ( DATA_RECORD( 3 ), X_INT) 

EQUIVALENCE ( DATA_RECORD( 4 ), Y_INT) 
EQUIVALENCE ( DATA_RECORD( 5 ), TIME_INT) 
EQUIVALENCE ( DATA_RECORD( 6 ), ATTS FLAG) 


CALL GKSSOPEN_GKS( 'SYS$ERROR:’ ) 
CALL GKS$OPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


RECORD BUFFER_LENGTH = 24 ; 

CALL GKS$INQ_STROKE STATE( WS ID, DEVICE_NUM, 

* GKSS$K_VALUE REALIZED, DIMENSION, ERROR_STATUS, 

* INPUT MODE, ECHO FLAG, TRANSFRM, NUM_ENTERED POINTS, 
* STROKE X, STROKE Y, PROMPT ECHO TYPE, ECHO AREA, 

* DATA RECORD, RECORD BUFFER LENGTH, RECORD SIZE ) 


Allow a buffer that is large enough. 
TRANSFRM = 0 


By specifying to DEC GKS to use the current attributes flag, you 
need to pass the 24 byte data record instead of the 52 byte record. 
ATTS_FLAG = GKS$K_ACF_CURRENT 


gaa AN 
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Example 7-14 (Cont.): Using a Stroke Logical Input Device in Sample 


Mode 





Cc 


300 
200 


To initialize a device, make sure it’s in request mode (the DEC 
GKS default). 

CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 

* GKSS$K_INPUT_ MODE REQUEST, GKS$K_ECHO ) 


CALL GKS$INIT_STROKE( WS_ID, DEVICE_NUM, 

* NUM_ENTERED_POINTS, STROKE X, STROKE_Y, TRANSFRM, 
* PROMPT ECHO TYPE, ECHO AREA, DATA_RECORD, 

* RECORD BUFFER_LENGTH ) 


CALL GKSS$SET_STROKE_MODE( WS_ID, DEVICE_NUM, 
* GKSS$K_INPUT_MODE_SAMPLE, GKS$K_ECHO ) 


Tell the user how many sets of stroke points to enter. 
CALL GKS$SET_TEXT _HEIGHT( LARGER ) 

CALL GKSSTEXT( 0.05, 0.95, 

* ‘Every 20 seconds, enter points.’) 

CALL GKSSTEXT( 0.05, 0.90, 

* ‘TIT will show the three fill areas.’) 


Obtain an event flag for the timer. 
CALL LIBSGET_EF( EVENT FLAG ) 

Do for three sets of stroke points. 
DO 200 INCR = 1, 3, 1 © 


Give the user a 20-second break. 

CALL SYSSBINTIM( ’0 :00:20’, TIME ) 

CALL SYSSSETIMR ( SVAL( EVENT FLAG ), ~( TIME ),,) 
CALL SYSSWAITFR( %VAL( EVENT FLAG ) ) 


Sample the stroke. 


CALL GKS$SAMPLE_STROKE( WS_ID, DEVICE_NUM, 
* TRANSFRM, NUM ENTERED POINTS, %DESCR( STROKE X ), 
* %DESCR( STROKE_Y ), RET SIZE_X, RET SIZE_Y ) 


RET_SIZE_BUF( INCR ) = MIN( RET SIZE X, RET SIZE Y ) 


Put the strokes in a buffer. 

DO 300 INCR2 = 1, RET_SIZE_BUF( INCR ), 1 
STROKE_BUFFER_X( INCR, INCR2 ) = STROKE_X( INCR2 ) 
STROKE_BUFFER_Y( INCR, INCR2 ) = STROKE_Y( INCR2 ) 
CONTINUE 


CONTINUE 
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Example 7-14 (Cont.): Using a Stroke Logical Input Device in Sample 
Mode 
Cc Free the event flag used for the timer. 
CALL LIBSFREE_EF( EVENT FLAG ) 
Cc Get rid of the stroke prompt... 
6 CALL GKSS$SET_STROKE_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_ REQUEST, GKS$K_ECHO ) 
Cc Present the corresponding fill areas. Press RETURN when you are 
Cc ready to view the next fill area. 
6 CALL GKSSCLEAR_WS( WS_ID, GKS$K_CLEAR_ALWAYS ) 


CALL GKSSTEXT( 0.05, 0.95, 

* ‘Here are the fill areas.’) 
CALL GKSSCREATE_SEG ( TEXT ) 
CALL GKSSTEXT( 0.05, 0.90, 

* ‘Press RETURN when ready.’ ) 
CALL GKSS$SCLOSE_SEG () 


CALL GKSS$SET_FILL_INT_STYLE( GKS$K_INTSTYLE_SOLID ) 
DO 400 INCR = 1, 3, 1 


C Put the current stroke in the temporary buffer. 
DO 500 INCR2 = 1, RET SIZE _BUF( INCR ), 1 
STROKE_X( INCR2 ) STROKE_BUFFER_X( INCR, INCR2 ) 
STROKE_Y( INCR2 ) STROKE_BUFFER_Y( INCR, INCR2 ) 

500 CONTINUE 


CALL GKS$FILL_AREA( RET SIZE _BUF( INCR ), 
* STROKE X, STROKE Y ) 
CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 
READ (5, *) 
IF ( INCR .EQ. 3 ) THEN 
CALL GKSSDELETE_SEG( TEXT ) 
ENDIF 
CALL GKSSREDRAW_SEG_ON_WS( WS_ID ) 


400 CONTINUE 


CALL GKS$DEACTIVATE_WS( WS _ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 
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The following numbers correspond to the numbers in the previous example: 


‘s) 


The call to SET STROKE MODE sets the input operating mode to 
sample. At this point in the program, the stroke prompt appears on the 
workstation surface and the user can enter or alter stroke points. 


This code creates a 20-second timer that allows the user to enter and 
alter a character string. For more information concerning these function 
calls, refer to the Introduction to VMS System Routines, and to the VMS 
Run-Time Library Routines Reference Manual. 


This call to SAMPLE STROKE retrieves the current input value (with- 
out the user having to trigger the device). The loop allows the user to 
enter three sets of stroke points. 


This code sets the correct size of the buffer and stores the stroke points 
in a two-dimensional array. 


The call to SET STROKE MODE returns the logical input device to 
request mode. At this point, the device handler removes the stroke 
prompt from the workstation surface and the user can no longer enter 
input. 

This code uses each of the sets of stroke points to create and display a 
fill area. 


Figure 7—28 illustrates the surface of the VT241 just before the program 
accepts the first set of stroke points. Notice that the user need only enter 
points (without triggering) and the program accepts the current set. Figures 
7-29 and 7-30 illustrate the remaining sets of stroke points entered by the 
user. Figures 7-31 through 7—33 show the fill areas. generated from the set 
of entered stroke points. 
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Figure 7-28: The Stroke Logical Input Device in Sample Mode—VT241 


Every 20 seconds, enter points. 
I’1]1 show the three fill areas, 


™ 
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Figure 7-29: The Stroke Logical Input Device in Sample Mode—VT241 


Every 20 seconds, enter points, 
I’11 show the three fill areas. 
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Figure 7-30: The Stroke Logical Input Device in Sample Mode—VT241 


Every 20 seconds, enter points. 
T’1ll show the three fill areas, 
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Figure 7-31: The Stroke Logical Input Device in Sample Mode—VT241 


Here are the fill areas. 
Press RETURN when ready, 


~~ 
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Figure 7-32: The Stroke Logical Input Device in Sample Mode—VT241 


Press RETURN when ready, 
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Figure 7~33: The Stroke Logical Input Device in Sample Mode—VT241 


Press RETURN when ready, 





2K-5832-HC 


Input Functions 7-193 


Sampling Input 
SAMPLE VALUATOR 


SAMPLE VALUATOR 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SAMPLE VALUATOR writes the current measure of the 
specified valuator logical input device to the corresponding output argument. 


Syntax 

GKS$SAMPLE_VALUATOR = (workstation_id, device_number, 

real_value) 

GSMVL _ (workstation_id, device_number, value) 

gsampleval (workstation_id, device_number, response) 
Arguments 

workstation_id 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the workstation identifier specified in a previous call to 
OPEN WORKSTATION. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that differentiates logical devices of the 
same class operating on the same workstation. 
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real_value 
data type: real 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the current measure of the 
valuator device. 


Error Messages 


Error | Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP 

20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 

25 GKS$_ERROR_25 Specified workstation is not open 
in routine **** 

38 GKS$_ERROR_38 Specified workstation is neither of 


category INPUT nor of category 
OUTIN in routine **** 


140 GKS$_ERROR_140 Specified input device is not 


present on workstation in routine 
KR RK 


142 GKS$_ERROR_142 Input device is not in SAMPLE 
mode in routine **** 


Program Example 
Example 7-15 illustrates the use of the function SAMPLE VALUATOR. 
Following the program example, Figures 7-34 through 7-36 illustrate the 
program’s effect on a VT241 workstation. 
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Example 7-15: Using a Valuator Logical Input Device in Sample Mode 


Cc This program initializes and samples valuator input from a VT241. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, PROMPT_ECHO TYPE, ERROR_STATUS, 
* INPUT MODE, ECHO_FLAG, RECORD BUFFER_LENGTH, RECORD SIZE, 
* INPUT STATUS, DEVICE_NUM, BOX, INCR, DUMMY_INTEGER, 
* NEW FRAME FLAG 
REAL ECHO AREA( 4 ), DATA _RECORD( 2 ), UPPER_LIMIT, 
* LOWER_LIMIT, VALUE, BOX_X( 5 ), BOX_Y( 5 ), LARGER, 
* XFORM MATRIX( 6 ) 
DATA WS_ID / 1-74; DEVICE NUM /1/, BOX /1 /, 
* LARGER / 0.03 / 
DATA BOX_X / 0.4, 0.6, 0.6, 0.4, 0.4 / 
DATA BOX_Y / 0.4, 0.4, 0.6, 0.6, 0.4 / 


Cc The elements in the data record are the upper and lower limits. 
EQUIVALENCE ( DATA_RECORD( 1 ), LOWER_LIMIT ) 
EQUIVALENCE ( DATA_RECORD( 2 ), UPPER_LIMIT ) 


CALL GKSS$OPEN_GKS( 'SYS$ERROR:’ ) 
CALL GKSS$OPEN_WS( WS_ID, GKS$K_CONID_ DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


RECORD_BUFFER_LENGTH = 8 

CALL GKS$INQ_VALUATOR_STATE( WS_ID, DEVICE_NUM, 
* ERROR STATUS, INPUT_MODE, ECHO FLAG, VALUE, 

* PROMPT ECHO TYPE, ECHO AREA, DATA_RECORD, 

* RECORD BUFFER_LENGTH, RECORD SIZE ) 


VALUE = 1.0 
UPPER_LIMIT = 2.0 
LOWER_LIMIT = 0.001 
Cc To initialize a device, make sure it’s in request mode (the DEC 


Cc GKS default). 
CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_REQUEST, GKS$K_ECHO ) 


CALL GKS$INIT_VALUATOR( WS_ID, DEVICE_NUM, 
* VALUE, PROMPT ECHO TYPE, ECHO_AREA, DATA_RECORD, 
* RECORD BUFFER_LENGTH ) 


@ CALL GKSSSET_VALUATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT MODE SAMPLE, GKS$K_ECHO ) 


(continued on next page) 
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Example 7-15 (Cont.): Using a Valuator Logical Input Device in Sample 


C 


Mode 


CALL GKS$SET_FILL_INT_STYLE( GKS$K_INTSTYLE_SOLID ) 
CALL GKS$SET_TEXT_HEIGHT( LARGER ) 


CALL GKSSCREATE_SEG( BOX ) 
CALL GKS$FILL_AREA( 5, BOX_X, BOX _Y ) 
CALL GKS$CLOSE_SEG() 


Inform the user about the task. 
CALL GKSSTEXT( 0.05, 0.95, 

* "Alter the box’’s size.’ ) 

CALL GKSSTEXT( 0.05, 0.90, 

* 'To stop, set the value to 2.0.’ ) 


DO WHILE ( VALUE .NE. 2.0 ) 


CALL GKS$SAMPLE_VALUATOR( WS_ID, DEVICE_NUM, 
* VALUE ) 


Scale the segment according to the VALUE argument. 
CALL GKSSEVAL_XFORM_ MATRIX( 0.5, 0.5, 0.0, 0.0, 0.0, 
* VALUE, VALUE, GKS$K_COORDINATES WC, XFORM_MATRIX ) 


IF ( VALUE .NE. 1.0 ) THEN 
CALL: GKS$SET_SEG_XFORM( BOX, XFORM MATRIX ) 
CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM FLAG ) 
ENDIF 
ENDDO 


Turn off the sample prompt. 


CALL GKS$SET_VALUATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT MODE REQUEST, GKSSK_ECHO ) 


CALL GKS$DEACTIVATE WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 

CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ The call to SET VALUATOR MODE sets the input operating mode to 
sample. At this point in the program, the valuator prompt appears on 
the workstation surface and the user can change the measure of the 
device. 
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@ This code creates a segment containing a square fill area. The program 
scales this box according to the sampled value of the valuator device. 


© This call to SAMPLE VALUATOR retrieves the current input value 
(without the user having to trigger the device). The loop ends when the 
user moves the prompt to the value 2.0. 


@ The call to SET VALUATOR MODE returns the logical input device to 
request mode. At this point, the device handler removes the valuator 
prompt from the workstation surface and the user can no longer enter 
input. 


Figure 7—34 illustrates the surface of the VT241 when the input mode is 
set. Figure 7-35 illustrates the surface of the VT241 when the user moves 
the prompt. Notice that the user need only move the prompt to another 
value (without triggering) and the program scales the segment accordingly. 
Figure 7—36 illustrates the surface of the VT241 when the program ends. 
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Figure 7-34: The Valuator Logical Input Device in Sample Mode—VT241 


Alter the box’s size, 
To stop, set the value to 2.0, 
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Figure 7-35: The Valuator Logical Input Device in Sample Mode—VT241 


2.000 
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Figure 7-36: The Valuator Logical Input Device in Sample Mode—VT241 
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Obtaining Input in Event Mode 


This section describes the functions used to remove, read, and flush input 
reports from the event queue. You should use AWAIT EVENT to fetch a 
report from the queue and to place it in the current event report entry in 
the DEC GKS state list. Also, AWAIT EVENT writes the logical input 
class of the device that accepted the current report to one of its output 
arguments. To read the input information from the current event report, 
call the appropriate GET class function. If you call one of the GET class 
functions for an event in the current event report that was not generated by 
a device of the corresponding class, you generate an error. 


Remember that repeated calls to one of the functions GET LOCATOR, 
GET STROKE, and so forth, will write the same values to the output 
arguments since these functions always obtain information from the current 
event report. The current event report does not change unless you call 
AWAIT EVENT to fetch another report from the queue. Once you do this, a 
subsequent call to one of the GET class functions obtains new input values. 


See Section 7.5 for information concerning event operating modes. 
This section describes the following functions: 

e AWAIT EVENT 

e FLUSH DEVICE EVENTS 

e GET CHOICE 

¢ GET LOCATOR 

¢ GET PICK 

¢ GET STRING 

¢ GET STROKE 

¢ GET VALUATOR 
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AWAIT EVENT 


Operating States: WSOP, WSAC, SGOP 


Description 


The function AWAIT EVENT examines the input queue for all input devices. 


DEC GKS searches the input queue for an event and, if the input queue 
is empty, suspends the application program until either of the following 
happens: | 

-e An event appears on the input queue. 


¢ The time period specified in the timeout argument expires. 


If you specify zero (0.0) as the timeout argument, DEC GKS checks the 
input queue immediately without suspending the application. 


When AWAIT EVENT checks the event input queue, its subsequent action 
depends on the state of the queue. If the queue contains reports, this 
function performs the following tasks: 


¢ Removes the oldest event report from the queue. 


¢ Writes information to the current event report entry in the DEC GKS 
state list. 


¢ Writes the event’s workstation identifier, input class, and logical device 
number to its corresponding output arguments. 


If the timeout period has expired, and if AWAIT EVENT finds the queue 
to be empty, this function writes GKS$K_INPUT_CLASS_NONE to its 
input_class argument. 


If you generate the queue-overflow error, this function still performs its task 
as described. See Section 7.5.3.3 for information concerning input-queue 
overflow. 
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Syntax 


GKS$AWAIT_EVENT (time_out, workstation_id, input_class, 
device_number) 


GWAIT  (time_out, workstation_id, in_class, device_number) 
gawaitevent (timeout, event) 


Arguments 
time_out 
data type: real 
access: read-only 
mechanism: by reference 


7-204 


This argument is the amount of time to wait for an event to appear in the 
input queue. This argument is specified in the following format: 


ss.hh 


Where ss is seconds and hh is hundredths of a second. This argument 
cannot be negative and cannot be larger than 356,400 seconds (99 hours). 


If this argument is zero (0.0), this function allows application execution to 
continue and either removes the oldest event or, if there are no events in the 
queue, returns GKS$K_INPUT_CLASS_NONE to the input_class argument. 


workstation_id 


data type: integer 
access: write-only 
mechanism: by reference 


This argument is the workstation identifier that corresponds to the logical 
input device that accepted the event. 
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input_class 


data type: integer 
access: write-only 
mechanism: by reference 


This argument is the input class that corresponds to the logical input device 
that accepted the event. This argument can be any of the following: 


Value Constant Description 

0 GKS$K_INPUT_CLASS_NONE Input queue is empty. 

1 GKS$K_INPUT_CLASS_LOCATOR Event from a locator device. 
2 GKS$K_INPUT_CLASS_STROKE Event from a stroke device. 

3 GKS$K_INPUT_CLASS_VALUATOR Event from a valuator device. 
4 GKS$K_INPUT_CLASS_CHOICE Event from a choice device. 

5 GKS$K_INPUT_CLASS_PICK Event from a pick device. 

6 GKS$K_INPUT_CLASS_STRING Event from a string device. 


device_number 


data type: integer 
access: write-only 
mechanism: by reference 


This argument is the device number that corresponds to the logical input 
device that accepted the event. 
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Error Messages 


Error Completion 

Number Status Code Message 

-20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state; GKS 
shall be in one of the states WSOP, 

. WSAC, or SGOP 

147 GKS$_ERROR_147 Input queue has overflowed in 
routine **** 

151 GKS$_ERROR_151 Timeout is invalid in routine **** 


Program Example 


To see an example of a call to this function, refer to Example 7-3. 
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FLUSH DEVICE EVENTS 


Operating States: WSOP, WSAC, SGOP 


Description 


The function FLUSH DEVICE EVENTS removes all events generated by 
one class of input device from the input queue. This function performs its 
task even if it generates the queue-overflow error message. 


See Section 7.5.3 for information concerning the flushing of the device queue, 
and see Section 7.5.3.3 for information concerning input-queue overflow. 


Syntax 

GKS$FLUSH_DEVICE_EVENTS (worksiation_id, input_class, 

device_number) 

GFLUSH  (workstation_id, in_class, device_number) 

gflushevents (workstation_id, class, device_number) 
Arguments 

workstation_id 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the workstation identifier that corresponds to the logical 
input device of the events to be removed from the input queue. 
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input_class 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the input class that corresponds to the logical input device 
of the events to be removed from the input queue. This argument can be 
any of the following: 


Value Constant Description 

1 GKS$K_INPUT_CLASS_LOCATOR Event from a locator device. 
2 GKS$K_INPUT_CLASS_STROKE Event from a stroke device. 

3 GKS$K_INPUT_CLASS_VALUATOR Event from a valuator device. 
4 GKS$K_INPUT_CLASS_CHOICE Event from a choice device. 

5 GKS$K_INPUT_CLASS_PICK Event from a pick device. 

6 GKS$K_INPUT_CLASS_STRING Event from a string device. 


device_number 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the device number that corresponds to the logical input 
device of the events to be removed from the queue. 
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Error 
Number 


—20 


20 
25 


38 
140 


147 


Program Example 


Obtaining Input in Event Mode 


Completion 
Status Code 


DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 


GKS$_ERROR_38 


GKS$_ERROR_140 


GKS$_ERROR_147 


FLUSH DEVICE EVENTS 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is neither of 
category INPUT nor of category 
OUTIN in routine **** 


Specified input device is not 


present on workstation in routine 
RK 


Input queue has overflowed in 
routine **** 


To see an example of a call to this function, refer to Example 7—5. 
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GET CHOICE 


Operating States: WSOP, WSAC, SGOP 


Description 


The function GET CHOICE obtains information from the current event 
report entry in the DEC GKS state list and writes the choice status and 
choice value to the output arguments. 


Syntax 
GKS$GET_CHOICE § (input_status, choice_value) 
GGTCH (in_status, ch_num) 
ggetchoice (response) 
Arguments 
input_status 
data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the status of the input 
process for the current event report. This argument can be either of the 
following values or constants: 


Value Constant Description 
1 GKS$K_STATUS_OK Input obtained. 
2 GKS$K_STATUS_NOCHOICE _ Triggered without choosing. 
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choice_value 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the integer representing the 
user’s choice for the current event report. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state; GKS 


shall be in one of the states WSOP, 
WSAC, or SGOP 


150 GKS$_ERROR_150 No input value of the correct class 
is in the current event report in 
routine **** 


Program Example 


Example 7-16 illustrates the use of the function GET CHOICE. 
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Example 7-16: Using a Choice Logical Input Device in Event Mode 


Cc This program initializes and accepts choice events from a VT241. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, DATA _RECORD( 3 ), NUM_CHOICES, SIZES( 3 ), 
ADDRESSES( 3 ), PROMPT_ECHO TYPE, ERROR_STATUS, 
INPUT MODE, ECHO_FLAG, RECORD _BUFFER_LENGTH, RECORD_SIZE, 
INPUT STATUS, INITIAL CHOICE, DEVICE_NUM, INPUT_CHOICE, 
INITIAL STATUS, NUM_POINTS, COLOR1, COLOR2, COLOR3, 
CLASS 
REAL ECHO AREA( 4 ), PX( 4 ), PY( 4 ), LARGER 
DATA PX / 0.05, 0.1, 0.075, 0.05 / 
DATA Py / 0.85, 0.85, 0.80, 0.85 / 
DATA NUM_POINTS / 4 /, COLOR1 / 1 /, COLOR2 / 2 /,. 
* COLOR3 / 3 /, LARGER / 0.03 / 


+ $ + & F 


CHARACTER*80 CURRENT STRINGS( 3 ) 
DATA WS_ID / 1 /, DEVICE_NUM / 1 / 


Cc First element in the data record is the number of choices. 
EQUIVALENCE ( DATA_RECORD(1), NUM_CHOICES ) 
CALL GKSSOPEN_GKS( ’SYS$ERROR:’ ) 
CALL GKSSOPEN _WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE_WS( WS_ID ) 


Cc Establish the size of the record buffer: 12 bytes. 
RECORD_BUFFER_LENGTH = 12 


The second element in the VT241 choice data record is the pointer to 
the array containing sizes of each choice character string. You need 
to initialize the pointer so that the array can be initialized. 
DATA_RECORD( 2 ) = %LOC( SIZES(1) ) 


aaa 


The third element in the VT241 choice data record is the pointer to the 
array containing the pointers to the strings to be used. You need 

to initialize the pointer so that the array can be initialized. 
DATA_RECORD( 3 ) = %LOC( ADDRESSES(1) ) 

ADDRESSES( 1 ) = %LOC( CURRENT_STRINGS( 1 ) ) 

ADDRESSES ( 2 ) = %LOC( CURRENT_STRINGS( 2 ) ) 

ADDRESSES ( 3 ) = %LOC( CURRENT STRINGS( 3 ) ) 


Qaaa 





(continued on next page) 
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Example 7-16 (Cont.): Using a Choice Logical Input Device in Event Mode 


Inquire about the default values. 

NUM_CHOICES = 3 

CALL GKS$INQ_CHOICE STATE( WS_ID, DEVICE_NUM, 

* ERROR_STATUS, INPUT_MODE, ECHO FLAG, INITIAL STATUS, 
* INITIAL CHOICE, PROMPT ECHO TYPE, ECHO AREA, 

* DATA RECORD, RECORD_! BUFFER . LENGTH, RECORD SIZE ) 


Set the initial status. 
INITIAL STATUS = GKS$K_STATUS_OK 


Establish sizes of prompt strings... 


SIZES( 1) = 4 
SIZES( 2) = 5 
SIZES( 3) = 4 


Establish locations of prompt strings... 
ADDRESSES ( 1 ) = %SLOC( ’Pink’ ) 
ADDRESSES( 2 ) = %LOC( ’Green’ ) 
ADDRESSES( 3 ) = %LOC( ‘’Blue’ ) 


To initialize a device, make sure it’s in request mode (the DEC 
GKS default). 

CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 

* GKS$K_INPUT_MODE_ REQUEST, GKS$K_| ECHO ) 


CALL GKSS$INIT_CHOICE( WS_ID, DEVICE_NUM, 
* INITIAL STATUS, INITIAL CHOICE, PROMPT ECHO TYPE, 
* ECHO AREA, DATA _RECORD, RECORD BUFFER_LENGTH ) 


CALL GKS$SET_CHOICE MODE( WS _ID, DEVICE _NUM, 
* GKS$K_INPUT_MODE_EVENT, GKS$K_ECHO ) 


Initialize color indexes. 
CALL GKS$SET_COLOR_REP ( WS_ID, COLOR1, 0.6258, 0.2142, 


* 0.2142 ) 

CALL GKS$SET_COLOR_REP( WS_ID, COLOR2, 0.1400, 1.000, 
* 0.1400 ) 

CALL GKSS$SET_COLOR_REP( WS_ID, COLOR3, 0.0, 0.0, 
* 0.8400 ) 


CALL GKS$SET_FILL_COLOR_INDEX( COLOR1 ) 
CALL GKS$SET_FILL_INT_STYLE( GKS$K_INTSTYLE_SOLID ) 





(continued on next page) 
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Cc Tell the user how to change colors. 
CALL GKS$SET_TEXT HEIGHT( LARGER ) 
CALL GKSS$TEXT( 0.05, 0.95, ’Move the arrow keys to’) 
CALL GKS$TEXT( 0.05, 0.90, ’change the triangle colors.’) 


Cc Do until the surface is full. 
DO WHILE ( PX( 2) .LT. 0.95 ) 


Cc Check the event queue. 
CALL GKSSAWAIT_EVENT( 0.0, WS_ID, CLASS, DEVICE_NUM ) 


IF ( CLASS .NE. GKS$K_INPUT_CLASS_ NONE ) THEN 
CALL GKS$GET_CHOICE( INPUT _STATUS, INPUT_CHOICE ) 
ENDIF 


Cc Depending on the event values, change the color. 

IF ( INPUT_CHOICE .EQ. 1 ) THEN 

CALL GKSS$SET_FILL_COLOR_INDEX ( COLOR1 ) 
ENDIF 
IF ( INPUT CHOICE .EQ. 2 ) THEN 

CALL GKS$SET_FILL_COLOR_INDEX( COLOR2 ) 
ENDIF 
IF ( INPUT CHOICE .EQ. 3 ) THEN 

CALL GKS$SET_FILL_COLOR_INDEX ( COLOR3 ) 
ENDIF 


Cc Draw the triangles. 
CALL GKSS$FILL_AREA ( NUM_POINTS, PX, PY ) 


Cc Adjust the position of the triangles. 
PY( 1 ) PY( 1) - 0.06 


PY( 2) = PY( 2) - 0.06 
PY¥( 3) = PY¥( 3) - 0.06 
PY¥( 4) = PY( 4) - 0.06 


(continued on next page) 
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ENDDO 


2 
) 
) 
) 
) 
) 
) 
) 
) 


-LT. 0.05 ) THEN 


) 

= 0.85 

= 0.85 

= 0.80 

= 0.85 

= PX( 1) + 0.06 
= PX( 2) + 0.06 
= PX( 3) + 0.06 
= PX( 4 ) + 0.06 


Turn off the event prompt. 


CALL GKS$SET_CHOICE MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_ MODE REQUEST, GKS$K_ECHO ) 


CALL GKS$DEACTIVATE WS( WS ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 


END 


The following numbers correspond to the numbers in the previous example: 
@ The call to SET CHOICE MODE sets the input operating mode to 


event. At this point in the program, the choice prompt appears on the 
workstation surface and the user can trigger the device to place an event 
report on the input queue. 

If there is an event report on the input queue, AWAIT EVENT removes 
the report and GET CHOICE retrieves the input values. Notice that 
the user must trigger the device (or the time specified in an argument 
to AWAIT EVENT must expire) to place an event report on the input 
queue. 

This code draws triangles in columns. 

The call to SET CHOICE MODE returns the logical input device to 
request mode. At this point, the device handler removes the choice 
prompt from the workstation surface and the user can no longer enter 
input. 
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The images generated by this program are identical to the images generated 
by Example 7—11. The difference is that the user must trigger the device (or 
allow the timeout argument for AWAIT EVENT to expire) before an event 
report appears on the input queue. Using sample mode, the application 
program controls the acceptance of the choice without user action. 
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GET LOCATOR 


Operating States: WSOP, WSAC, SGOP 


Description 


The function GET LOCATOR obtains information from the current event 
report entry in the DEC GKS state list and writes the normalization 
transformation and the X and Y world coordinate point values to the output 
arguments. 


Syntax 
GKS$GET_LOCATOR (transformation_number, world_x, 
world_y) 
GGTLC (xform, pos_x, pos_y) 
ggetloc (response) 
Arguments 
transformation_number 
data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the normalization transfor- 
mation number used to translate the current event’s input point to a world 
coordinate point. 
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world_x 
world_y | 
data type: real 
access: write-only 
mechanism: by reference 


These are the arguments to which DEC GKS writes the X and Y world 
coordinate values for the current event record. 


Error Messages 


Error Completion 
Number Status Code Message 
20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 
7 GKS$_ERROR_7 GKS not in proper state; GKS 


shall be in one of the states WSOP, 
WSAC, or SGOP 


150 GKS$_ERROR_150 No input value of the correct class 
is in the current event report in 
routine **** 


Program Example 


To see an example of a call to this function, refer to Example 7-3. 
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GET PICK 


Operating States: WSOP, WSAC, SGOP 


Description 


The function GET PICK obtains information from the current event report 
entry in the DEC GKS state list and writes the input status, segment name, 
and pick identifier to the output arguments. 


Syntax 
GKS$GET_PICK (input_status, segment_name, pick_id) 
GGTPK (in_status, segment_name, pick_id) 
ggetpick (response) 
Arguments 
input_status 
data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the status of the input 
values in the current event report. This argument can be either of the 
following values or constants: 


Value Constant Description 
1 GKS$K_STATUS_OK Input obtained. 
2 GKS$K_STATUS_NOPICK Triggered without picking. 
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segment_name 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the integer representing the 
segment name in the current event report. 


pick_id 

data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the integer representing the 
pick identifier for the current event report. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state; GKS 


shall be in one of the states WSOP, 
WSAC, or SGOP 


150 GKS$_ERROR_150 No input value of the correct class 
is in the current event report in 
routine **** 


Program Example 


To see an example of a call to this function, refer to Example 7-4. 
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GET STRING 


Operating States: WSOP, WSAC, SGOP 


Description 


The function GET STRING obtains information from the current event 
report entry in the DEC GKS state list and writes the string, the string size, 
and the number of characters written to the output arguments. 


When activating string input, the following two buffers exist: 


¢ The application’s string buffer, whose size you specify when you pass the 
buffer argument by descriptor to GET STRING. 


¢ ©The logical input device’s string buffer, whose size you can specify in the 
call to INITIALIZE STRING. 


When reading a string from the current event report, DEC GKS removes 
characters up to the number that fit into the application’s buffer. If 

the size of the string in the current event report is larger than the 
application’s buffer, you need to call GET STRING again, using a larger 
application buffer, in order to obtain the entire string contained in the 
report. (Remember that the string contained in the current report does not 
change until you call AWAIT EVENT to replace the current report.) 


NOTE 


The initial string only appears in the first generated string event 
report. Subsequent string reports do not contain the initial string. 
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Syntax 
GKS$GET_STRING (string_buffer, string_size, 
report_string_size) 
GGTST (num_char, cstring) 
GGTST- Subset (num_char, cstring) 
ggetstring (response) 


Arguments 
string_buffer 
data type: string 
access: write-only 
mechanism: by descriptor 


This is the argument to which DEC GKS writes the input character string. 
This is the application’s buffer. 


string_size 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the number of bytes in the 
string accepted from the current event. 


report_string_size 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the total size of the string 
found in the current event report. If this value is larger than string_size, 
you may want to call GET STRING, passing a larger buffer, to obtain the 
entire string contained in the report. 
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Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
7 GKS$_ERROR_7 

150 GKS$_ERROR_150 


Program Example 


GET STRING 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state; GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP 


No input value of the correct class 
is in the current event report in 
routine **** 


Example 7-17 illustrates the use of the function GET STRING. 
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Example 7-17: Using a String Logical Input Device in Event Mode 





This program initializes and accepts string events from a VT241. 
IMPLICIT NONE . 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, DATA_RECORD( 2 ), 

* PROMPT ECHO TYPE, ERROR_STATUS, BUFFER_LENGTH, 

* INPUT MODE, ECHO FLAG, RECORD BUFFER_LENGTH, 

* RECORD _SIZE, INPUT_STATUS, DEVICE_NUM, STRING _SIZE, 
* CUR_POSITION, REPORT STRING SIZE, INCR, INCR2, CLASS 
REAL ECHO AREA( 4 ), START_X, START_Y, X_VECTOR, Y_VECTOR, 
* LARGER, TIME 

CHARACTER*31 INITIAL STRING, STRING_BUFFER 

DATA WS_ID / 1 /, DEVICE_NUM / 1 /, LARGER / 0.03 /, 
* TIME / 20.0 / 


First element in the data record is length of the buffer that 
contains the input string. 

EQUIVALENCE( DATA_RECORD( 1 ), BUFFER_LENGTH ) 

EQUIVALENCE ( DATA_RECORD( 2 ), CUR_POSITION ) 


CALL GKSS$OPEN_GKS( 'SYSSERROR:’ ) 
CALL GKSSOPEN WS( WS_ID, GKS$K_CONID_ DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


RECORD BUFFER LENGTH = 8 

CALL GKS$INQ_STRING STATE( WS_ID, DEVICE_NUM, 

* ERROR_STATUS, INPUT MODE, ECHO_FLAG, INITIAL_STRING, 

* STRING SIZE, PROMPT ECHO TYPE, ECHO AREA, DATA_RECORD, 
* RECORD BUFFER_LENGTH, RECORD SIZE ) 


ECHO AREA( 1) = 437 
BUFFER_LENGTH = 31 
CUR_POSITION = 1 


To initialize a device, make sure it’s in request mode (the DEC 
GKS default). 

CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 

* GKS$K_INPUT_MODE REQUEST, GKS$K_ECHO ) 


CALL GKSS$INIT_STRING( WS_ID, DEVICE_NUM, ’ ', 
* PROMPT ECHO TYPE, ECHO AREA, DATA_RECORD, 
* RECORD _BUFFER_LENGTH ) 





(continued on next page) 
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Tell the user what is happening. 

CALL GKS$SET_TEXT_HEIGHT ( LARGER ) 

CALL GKS$TEXT( 0.05, 0.95, ’Every 20 seconds, type a string.’) 
CALL GKS$TEXT( 0.05, 0.90, ’I will use them in my design.’) 


CALL GKS$SET_STRING MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_EVENT, GKS$K_ECHO ) 


Set the initial text settings and attributes. 
START_X = 0.05 
START_Y = 0.70 
X_VECTOR = 0.0 
Y_VECTOR 1.0 


Do for three lines. 
DO 200 INCR = 1, 3, 1 


IF ( INCR .NE. 1 ) THEN 


Ask for a string... 

CALL GKS$SET_TEXT_UPVEC( 0.0, 1.0 ) 

CALL GKSSTEXT( 0.05, 0.85, 

* ‘Please enter a string.’ ) 

CALL GKS$SET_TEXT_UPVEC( X_VECTOR, Y_VECTOR ) 


Check the event queue. 
CALL GKS$AWAIT_EVENT( TIME, WS_ID, CLASS, DEVICE_NUM ) 


If the user entered a string, get it... 


IF ( CLASS .NE. GKS$K_INPUT_CLASS_NONE ) THEN 
CALL GKS$GET_STRING( STRING_BUFFER, STRING_SIZE, 


* REPORT_STRING SIZE ) 
Otherwise, ask for a string... 
ENDIF 
ELSE 


Provide the first string. 
STRING BUFFER = ‘I will give you the first string.’ 
ENDIF 





(continued on next page) 
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Cc Create a design with a text string. 
4) DO 300 INCR2 = 1, 3, 1 
CALL GKSSSET_TEXT_UPVEC ( X_VECTOR, Y_VECTOR ) 
CALL GKSSTEXT ( START X, START _Y, 
* STRING BUFFER ) 
X_VECTOR = X_VECTOR + 0.1 
¥_VECTOR = Y_VECTOR - 0.1 
300 CONTINUE 
Cc Reset variables. 
START_Y = START_Y - 0.01 
STRING BUFFER = ' ' 


200 CONTINUE 


Cc Turn off the event prompt. 
6 CALL GKS$SET_STRING_MODE( WS_ID, DEVICE_NUM, 
* GKSSK_INPUT_MODE REQUEST, GKS$K_ECHO ) 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ Changing the value of variable ECHO_AREA( 1 ) widens the echo area 
so that the user can enter a larger string than the one which the default 
area allows. 


@ The call to SET STRING MODE sets the input operating mode to 
event. At this point in the program, the string prompt appears on the 
workstation surface and the user can trigger the device to enter an event 
report on the input queue. 

© If there is an event report on the input queue, AWAIT EVENT removes 
the report and GET STRING retrieves the input values. Notice that 
the user must trigger the device (or the time specified in an argument 
to AWAIT EVENT must expire) to place an event report on the input 
queue. 

@ This code outputs the strings by adjusting the character-up vector. This 
creates a “pinwheel” design on the workstation surface. 
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© The call to SET STRING MODE returns the logical input device to 
request mode. At this point, the device handler removes the string 
prompt from the workstation surface and the user can no longer enter 
input. 


The images generated by this program are identical to the images gener- 
ated by Example 7-13. The difference is that the user must trigger the 
device (or allow the timeout argument for AWAIT EVENT to expire) before 
an event report appears on the input queue. Using sample mode, the ap- 
plication program controls the acceptance of the string without user action 
(triggering). 
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GET STROKE 


Operating States: WSOP, WSAC, SGOP 


Description 


7-228 


The function GET STROKE obtains information from the current event 
report entry in the DEC GKS state list and writes the normalization 
transformation, the number of entered points, the stroke point values, and 
the number of accepted stroke point values to the output arguments. 


When activating stroke input, the following two buffers exist: 


¢ The application’s stroke buffer, whose size you specify when you pass the 
buffer argument by descriptor to GET STROKE. 


¢ The logical input device’s stroke buffer, whose size you can specify in the 
call to INITIALIZE STROKE. 


When reading stroke points from the current event report, DEC GKS 
removes points up to the number that fit into the application’s buffer. 

If the size of the stroke in the current event report is larger than the 
application’s buffer, you need to call GET STROKE again, using a larger 
application buffer, in order to obtain the entire stroke contained in the 
report. (Remember that the stroke contained in the current report does not 
change until you call AWAIT EVENT to replace the current report.) 


NOTE 


The initial stroke appears only in the first generated stroke 
event report. Subsequent stroke reports do not contain the initial 
stroke. 
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Syntax 
GKS$GET_STROKE (transformation_number, 
num_entered_points, stroke_buffer_x, 
stroke_buffer_y, stroke_size_x, 
stroke_size_y) 
GGTSK (max_pts, xform, num_pts, px, py) 
ggetstroke (response) 
Arguments 
transformation_number 
data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the number of the 
normalization transformation used to translate points in the current event 
report to world coordinate points. 


num_entered_points 


data type: integer 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the number of points in the 
stroke in the current event report. 


stroke_buffer_x 
stroke_buffer_y 


data type: array (real) 
access: write-only 
mechanism: by descriptor 


These are the arguments to which DEC GKS writes the X and Y world 
coordinate values from the current event report. These arguments are the 
application’s stroke buffer. 
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stroke_size_x 
stroke_size_y 


data type: integer 
access: write-only 
mechanism: by reference 


These are the arguments to which DEC GKS writes the number of stroke 
points actually accepted from the current event report and placed in the 
application buffer. If the values in these arguments are less than 
num_entered_poinits, then you may want to call GET STROKE again, 
passing a larger bufffer, to obtain the entire stroke entered. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state; GKS 


shall be in one of the states WSOP, 
WSAC, or SGOP 


150 GKS$_ERROR_150 No input value of the correct class 
is in the current event report in 
routine **** 


Program Example 


Example 7—18 illustrates the use of the function GET STROKE. 
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ple 7-18: Using a Stroke Logical Input Device in Event Mode 


This program initializes and accepts stroke events from a VT241. 
IMPLICIT NONE 
INCLUDE ’SYS$LIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, DATA_RECORD( 6 ), BUFFER_SIZE, 
DIMENSION, PROMPT ECHO TYPE, ERROR_STATUS, 
TRANSFRM, NUM_ENTERED POINTS, INPUT_MODE, ECHO _ FLAG, 
RECORD | BUFFER . LENGTH, RECORD SIZE, INPUT_STATUS, DEVICE_NUM, 
RET SIZE X, RET SIZE _Y, I, EDIT POSITION, ATTS_FLAG, TEXT, 
INCR, INCR2, RET SIZE BUF( 3 ), CLASS 
REAL BCHO_AREA( 4 ), STROKE _X( 50 ), 


* STROKE ¥( 50 ), X_INT, Y_INT, TIME_INT, 
* STROKE BUFFER_X( 3, 50 ), STROKE _BUFFER_Y( 3, 50 ), 
* LARGER, TIME 


DATA WS_ID / 1 /, DEVICE_NUM / 1 /, TEXT / 1 /, 


* LARGER / 0.03 /, TIME / 20.0 / 


ecord is the buffer size. 
, BUFFER_SIZE) 

, EDIT POSITION) 
, X_INT) 

, Y_INT) 
, 

c 


First element in the data r 
EQUIVALENCE ( DATA_RECORD( 1 
EQUIVALENCE ( DATA_RECORD( 2 
EQUIVALENCE ( DATA_RECORD( 3 
EQUIVALENCE ( DATA_RECORD( 4 
EQUIVALENCE ( DATA_RECORD( 5 
EQUIVALENCE ( DATA_RECORD( 6 


TIME INT) 
ATTS FLAG) 


CALL GKSSOPEN_GKS( ’SYS$ERROR:’ ) 
CALL GKSSOPEN | | WS( WS_ID, GKS$K_CONID_ DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE _WS( WS_ID ) 


RECORD_BUFFER_LENGTH = 24 

CALL GKS$INQ_STROKE_STATE( WS_ID, DEVICE_NUM, 
GKS$K_VALUE_ REALIZED, DIMENSION, ERROR_STATUS, 

INPUT MODE, ECHO FLAG, TRANSFRM, NUM_ENTERED POINTS, 
STROKE _X, STROKE_Y, PROMPT ECHO TYPE, ECHO AREA, 
DATA_RECORD, RECORD BUFFER_LENGTH, RECORD_SIZE ) 


Allow a buffer that is large enough. 
BUFFER_SIZE = 256 


By specifying to DEC GKS to use the current attributes flag, you 
need to pass the 24 byte data record instead of the 52 byte record. 
ATTS FLAG = GKS$K_ACF_CURRENT 
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GET STROKE 
Example 7-18 (Cont.): Using a Stroke Logical Input Device in Event 
Mode 
Cc To initialize a device, make sure it’s in request mode (the DEC 


Cc GKS default). 
CALL GKS$SET_LOCATOR_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_ REQUEST, GKS$K_ECHO ) 


CALL GKSSINIT_STROKE( WS_ID, DEVICE_NUM, 

* NUM_ENTERED POINTS, .STROKE_X, STROKE Y, TRANSFRM, 
* PROMPT ECHO_TYPE, ECHO AREA, DATA_RECORD, 

* RECORD_BUFFER_LENGTH ) 


1] CALL GKS$SET_STROKE MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_EVENT, GKS$K_ECHO ) 


Cc Tell the user how many sets of stroke points to enter. 
CALL GKS$SET_TEXT_HEIGHT ( LARGER ) 
CALL GKSSTEXT( 0.05, 0.95, 
* ‘Every 20 seconds, enter points.’) 
CALL GKSSTEXT( 0.05, 0.90, 
* ‘TIT will show the three fill areas.’) 


Cc Do for three sets of stroke points. 
DO 200 INCR = 1, 3, 1 


Cc Check the event queue. 
CALL GKSSAWAIT_EVENT( TIME, WS_ID, CLASS, DEVICE_NUM ) 


Cc If the user entered a stroke, get it... 


e IF ( CLASS .NE. GKS$K_INPUT_CLASS NONE ) THEN 
CALL GKS$GET_STROKE( TRANSFRM, NUM ENTERED POINTS, 
x %DESCR( STROKE_X ), %DESCR( STROKE_Y ), 
* RET_SIZE_X, RET SIZE Y ) 
ENDIF 


RET SIZE_BUF( INCR ) = MIN( RET SIZE _X, RET_SIZE Y ) 


(continued on next page) 
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300 
200 
Cc 


Cc 
Cc 


500 


400 


Mode 


Put the strokes in a buffer. 

DO 300 INCR2 = 1, RET_SIZE_BUF( INCR ), 1 

STROKE BUFFER_X( INCR, INCR2 ) STROKE_X( INCR2 ) 
STROKE BUFFER_Y( INCR, INCR2 ) STROKE _Y( INCR2 ) 
CONTINUE 


CONTINUE 


Get rid of the stroke prompt... 


CALL GKS$SET_STROKE MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT MODE_REQUEST, GKS$K_ECHO ) 


Present the corresponding fill areas. Press RETURN when you are 
ready to view the next fill area. 


CALL GKSS$CLEAR_WS( WS_ID, GKS$K_CLEAR_ALWAYS ) 
CALL GKSSTEXT( 0.05, 0.95, 

* ‘Here are the fill areas.’) 

CALL GKS$CREATE_SEG( TEXT ) 

CALL GKS$TEXT( 0.05, 0.90, 

* ‘Press RETURN when ready.’) 

CALL GKS$CLOSE_SEG () 


CALL GKS$SET_FILL_INT_STYLE( GKS$K_INTSTYLE_SOLID ) 
DO 400 INCR = i, 3, 1 


Put the current stroke in the temporary buffer. 

DO 500 INCR2 = 1, RET _SIZE BUF( INCR ), 1 
STROKE_X( INCR2 ) = STROKE_BUFFER_X( INCR, INCR2 ) 
STROKE Y( INCR2 ) = STROKE_BUFFER_Y( INCR, INCR2 ) 
CONTINUE 


CALL GKS$FILL_AREA( RET_SIZE_BUF( INCR ), 
* STROKE _X, STROKE Y ) 
CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 
READ (5, *) 
IF ( INCR .EQ. 3 ) THEN 
CALL GKSS$DELETE_SEG( TEXT ) 
ENDIF 
CALL GKS$REDRAW_SEG ON WS( WS_ID ) 


CONTINUE 


(continued on next page) 
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Example 7-18 (Cont.): Using a Stroke Logical Input Device in Event 
Mode 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKSS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ The call to SET STROKE MODE sets the input operating mode to 
event. At this point in the program, the stroke prompt appears on the 
workstation surface and the user can enter stroke points, trigger the 
device, and enter the event report on the input queue. 


@ If there is an event report on the input queue, AWAIT EVENT removes 
the report and GET STROKE retrieves the input values. Notice that 
the user must trigger the device (or the time specified in an argument 
to AWAIT EVENT must expire) to place an event report on the input 
queue. 


© This code sets the correct size of the buffer and stores the stroke points 
in a two-dimensional array. 


@ The call to SET STROKE MODE returns the logical input device to 
request mode. At this point, the device handler removes the stroke 
prompt from the workstation surface and the user can no longer enter 
input. 

@ This code uses each of the sets of stroke points to create and display a 
fill area. 


The images generated by this program are identical to the images generated 
by Example 7-14. The difference is that the user must trigger the device 
(or allow the timeout argument for AWAIT EVENT to expire) before an 
event report appears on the input queue. Using sample mode, the appli- 
cation program controls the acceptance of the stroke without user action 
(triggering). 
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GET VALUATOR 


Operating States: WSOP, WSAC, SGOP 


Description 


The function GET VALUATOR obtains information from the current event 
report entry in the DEC GKS state list and writes the real value output 


argument. 


Syntax 
GKS$GET_VALUATOR  (real_value) 
GGTVL (value) 
ggetval (response) 
Arguments 
real_value 
data type: real 
access: write-only 
mechanism: by reference 


This is the argument to which DEC GKS writes the current measure of the 
valuator device. 
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Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state; GKS 


shall be in one of the states WSOP, 
- WSAC, or SGOP 


150 GKS$_ERROR_150 No input value of the correct class 
is in the current event report in 
routine **** 


Program Example 


To see an example of a call to this function, refer to Example 7-4. 
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Segment Functions 


The DEC GKS segment functions create, manipulate, and delete stored 
groups of output primitives called segments. The segment functions can be 
divided into the following categories: 


Category 
Using Segments 


Segment Attributes 


Segment Transformations 


GKS Functions 


ASSOCIATE SEGMENT WITH WORKSTATION 
CLOSE SEGMENT 

COPY SEGMENT TO WORKSTATION 

CREATE SEGMENT 

DELETE SEGMENT 

DELETE SEGMENT FROM WORKSTATION 
INSERT SEGMENT 

RENAME SEGMENT 


SET DETECTABILITY 
SET HIGHLIGHTING 

SET SEGMENT PRIORITY 
SET VISIBILITY 


ACCUMULATE TRANSFORMATION MATRIX 
EVALUATE TRANSFORMATION MATRIX 
SET SEGMENT TRANSFORMATION 


When producing output, you may wish to reproduce a graphic image at 
different positions within a single picture, possibly across different devices, 
and possibly at different points during program execution. It is inefficient to 
call all the DEC GKS output and attribute functions every time you want to 
reproduce such an image. DEC GKS provides a method of storing groups of 
output primitives, output attributes, and clipping information in a segment. 
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8.1 Creating, Using, and Deleting Segments 


To use segments, your workstation should be one of the categories GKS$K_ 
WSCAT_OUTPUT, GKS$K_WSCAT_OUTIN, GKS$K_WSCAT_MO, or 
GKS$K_WSCAT_WISS (described in Section 8.2). When you create a 
segment, the segment is stored on all active workstations. 


To create a segment, DEC GKS must be in the operating state GKS$K_ 
WSAC (at least one workstation active). When DEC GKS is in this state, 
you can call CREATE SEGMENT, which creates a segment on all active 
workstations. The only argument passed to CREATE SEGMENT is the 
segment name. You use a segment name to identify a particular segment. 


After you call the function CREATE SEGMENT, the DEC GKS operating 
state changes to GKS$K_SGOP (segment open). Subsequent calls to the 
DEC GKS output and output attribute functions produce primitives that are 
stored in the segment on all active workstations. When you have created 
the desired image, call the function CLOSE SEGMENT. This call closes 

the segment, causing the DEC GKS operating state to change back to 
GKS$K_WSAC. 


For a clearer understanding of the segment creation process, review the 
following code example: 


INTEGER BOX, NUM POINTS, WS_ID 
REAL X_VALUES( 5 ), Y _ VALUES (5 


) 
DATA X_VALUES / 0.0, 120;- 30; . 0, 0.0 / 
DATA Y_VALUES / 0.0, 0.0, 1.0, 1.0, 0.0 / 
POINTS / 5 / 


DATA WS _ ID /1/, BOX/1/, come 
CALL GKSS$ACTIVATE_WS( WS_ID ) 


CALL GKS$CREATE_SEG( BOX ) 
CALL GKS$POLYLINE( NUM_POINTS, X_VALUES, Y_VALUES ) 
CALL GKS$CLOSE_SEG() 


In this code example, the workstation ws_id stores the segment box that 
contains an outline of a box. 
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When you call the function CREATE SEGMENT, the DEC GKS operating 
state changes from GKS$K_WSAC to GKS$K_SGOP. GKS$K_SGOP 
signifies that a segment is open, or being created. Also, calling CREATE 
SEGMENT establishes the segment state list associated with the segment 
name, and DEC GKS records the segment name (in the DEC GKS state list) 
as the name of the currently open segment. 


Segments cannot contain other segments, or in other words, segments 
cannot be nested. Therefore, if you call CREATE SEGMENT, you must call 
CLOSE SEGMENT before you attempt to call CREATE SEGMENT again. 
Until you call CLOSE SEGMENT, DEC GKS associates all generated output 
primitives with the name of the open segment. When you call CLOSE 
SEGMENT, the DEC GKS operating state changes from GKS$K_SGOP back 
to GKS$K_WSAC. After you close a segment, you cannot reopen the segment 
to add more output primitives. 


If you need to, you can rename the segment using the function RENAME 
SEGMENT. If you are keeping an ordered list of segments, calls to this 
function may be useful. 


There are three ways to delete segments. If you use the function DELETE 
SEGMENT FROM WORKSTATION, DEC GKS deletes the segment from 
the specified workstation. If you use DELETE SEGMENT, DEC GKS 
deletes the specified segment from all workstations storing the segment. If 
you call CLEAR WORKSTATION, and if the surface is cleared, you delete 
all segments stored on that workstation. 


For more information concerning the DEC GKS operating states or the 
segment state list, refer to Chapter 3, Control Functions. 


NOTE 


If you store primitives in a segment, and if you want to be able 
to change the primitive’s appearance elsewhere in the program, 
you must set the primitive’s ASF to be GKS$K_ASF_BUNDLED 
before you generate the primitive. In this way, the primitive’s 
ASF is stored in the segment with the primitive. If you want to 
change the primitive’s appearance, you call the appropriate SET 
REPRESENTATION function for the primitive’s bundle index. If 
you store the primitive in a segment using individual attributes, 
the appearance of the primitive cannot be changed after primitive 
generation. For more information, refer to Chapter 5, Output 
Attribute Functions. 
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8.1.1 Pick Identification 


One of the DEC GKS logical input classes is the pick input class. Through 
this process, the user can choose a segment, and possibly a portion of the 
segment, as displayed on the surface of the workstation. 


The following is an example of a call requesting pick input: 


CALL GKS$REQUEST_PICK( 1, ARG_1, ARG 2, 
‘* SEGMENT NAME, PICK_ID ) 


The arguments segment_name and pick_id are write-only arguments. At the 
completion of the function call, segment_name contains the name value of 
the chosen segment. 


Also, after completion of the function call, the argument pick_id contains a 
value called the pick identifier of the primitive chosen during pick input. 
The pick identifier is a numeric output attribute. Like other output attribute 
values (line type, line width, color, text alignment, and so forth), the pick 
identifier is bound to an output primitive at the time of generation, and 
you cannot change its value. However, you can change the current pick 
identifier value before generating each output primitive. In doing so, DEC 
GKS associates a different numeric pick identifier value with each generated 
primitive. . 

During segment creation, you can use pick identifiers to establish a hier- 
archy within the segment. During pick input, DEC GKS returns the same 
segment name if the pick prompt touches the same segment, but may return 
different pick identifiers depending on which primitive within the segment 
the pick prompt touches. 


For example, Figure 8-1 shows five distinct output primitives (one line and 
four markers). The following example shows how to assign different pick 
identifiers to distinct primitives within the same segment. 
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Figure 8-1: Primitives Within a Segment 





Each of the five primitives within this segment can have 
a different pick identifier. 
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° 


Cc The segment’s name is 99. 


CALL GKS$CREATE_SEG( 99 


) 


Cc The line’s pick identifier is 1. 


CALL GKSS$SET_ PICK ID( 1 


) 


CALL GKS$POLYLINE( 5, X_VALUES, Y_VALUES ) 


Cc The marker in the upper 
CALL GKSSSET_PICK_ID( 2 
CALL GKSSPOLYMARKER( 1, 


Cc The marker in the upper 
CALL GKSSSET_PICK_ID( 3 
CALL GKSSPOLYMARKER( 1, 


Cc The marker in the lower 
CALL GKSS$SET_PICK_ID( 4 
CALL GKSSPOLYMARKER( 1, 


Cc The marker in the lower 
CALL GKS$SET_PICK_ID{ 5 
CALL GKSSPOLYMARKER( 1, 


CALL GKSS$CLOSE_SEG () 


° 
e 


left corner has a pick identifier of 2. 


) 
X_VALUE_1, Y_VALUE_1 ) 


right corner has a pick identifier of 3. 


) 
X_VALUE_2, Y_VALUE_2 ) 


left corner has a pick identifier of 4. 


) 
X_VALUE_3, Y_VALUE_3 ) 


right corner has a pick identifier of 5. 


) 
X VALUE _4, Y_VALUE_4 ) 
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Figure 8-2 illustrates the pick identifiers returned depending on the position 
of the pick prompt during input. To see how to use pick identifiers, refer 

to the program example for SET PICK IDENTIFIER in cee 5, Output 
Attribute Functions. 


Figure 8-2: Returned Pick Identifiers 





Given the position of each of the prompts, the graphics 
handler returns the pick identifier value listed in each 
prompt. For all prompts, the graphics handler returns 
the segment name 99. 
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8.2 Workstations and Segment Storage 


When DEC GKS stores a segment on an active GKS$K_WSCAT_OUTPUT, 
GKS$K_WSCAT_OUTIN, or GKS$K_WSCAT_MO workstation, the method 
of storage is called workstation dependent segment storage (WDSS). 

On these workstations, you can control the segment attributes (see 

Section 8.4), you can move or alter the shape of the segment using the 
segment transformation functions (see Section 8.4.4.1), or you can delete the 
segment (either from a single workstation or from all workstations storing 
the segment). 


If you are creating segments using the WDSS method of storage, you 
cannot copy a segment from one workstation to another. Also, you cannot 
recall a segment once it has been deleted from a workstation. You can only 
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alter the segment’s position within the picture by changing the segment 
transformation. 


To copy a segment, or to reassociate a segment with a workstation after 
deletion from that particular workstation, you need to store the segment in 
workstation independent segment storage (WISS). Once a segment is stored 
in WISS, the segment is independent of any workstation and can be copied 
from WISS to other workstations. 


By storing a segment on a WISS workstation, you can delete a segment from 
a particular workstation (that is not WISS). Then, when you need to use 
the deleted segment later in the program, you can associate the segment 
stored on WISS with the other workstation, copy the segment to the other 
workstation, or insert the segment’s primitives into the output stream of the 
other workstation. 


If you associate a segment stored on a WISS workstation with another 
workstation, the other workstation stores an identical segment. If you copy 
a segment from a WISS workstation to another workstation, the segment’s 
primitives are copied to the surface of the second workstation, but the second 
workstation does not store them in a segment. If you insert a segment into 
the output stream of another workstation, DEC GKS transforms and then 
copies all the segment’s primitives onto the surface of the other workstation, 
but the second workstation does not store them in a segment. If you are 
creating a segment, you can insert another segment’s primitives into the 
newly created segment, but those primitives become part of the new segment 
and are no longer bound by the old segment name (see INSERT SEGMENT 
in this chapter for more information). 


DEC GKS implements the WISS data structure as a workstation. To store 
a segment using WISS, open and then activate WISS specifying GKS$K_ 
WSTYPE_WISS (value 5) as the workstation type. When you open WISS, 
you can specify GKS$K_CONID_DEFAULT as the connection identifier 
argument. (If you specify GKS$K_WSTYPE_WISS, DEC GKS ignores the 
connection identifier argument.) 


Once you activate the WISS workstation and create segments, you can use 
the DEC GKS functions ASSOCIATE SEGMENT WITH WORKSTATION, 
COPY SEGMENT TO WORKSTATION, and INSERT SEGMENT. 
Example 8-1 shows the difference between ASSOCIATE SEGMENT 
WITH WORKSTATION and COPY SEGMENT TO WORKSTATION. To 
see a program example using INSERT SEGMENT, refer to the appropriate 
function description in this chapter. 
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Example 8-1: Comparing ASSOCIATE SEGMENT WITH WORKSTATION 
and COPY SEGMENT TO WORKSTATION 





Cc This program draws a house in the lower left corner of the 
Cc screen and a line of text in the upper left corner. The program 
Cc redraws the segments. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, LOWER_LEFT_ CORNER, HOUSE, 
* UPPER_LEFT CORNER, WISS, TITLE, NUM_POINTS 
REAL PX ( 9 ), PY ( 9 ), WORLD _X, WORLD _Y, LARGER 
DATA PX / .4, .1, .1, .4, .25, «1, 1.4, «4, «1 / 
DATA PY / .1, .1, .7, .7, .9, «7, «1, .7, .1 / 
DATA NUM_POINTS / 9 /, LOWER_LEFT CORNER / 1 /, 
* HOUSE / 1 /, UPPER_LEFT_ CORNER / 2 /, WISS / 2 /, 
* TITLE / 2 /, WORLD_X / 0.1 /, WORLD Y / 0.5 /, 
* LARGER / 0.03 /, WS_ID/ 1 / 
CALL GKS$OPEN_GKS( '’SYSSERROR:’ ) 
CALL GKSSOPEN_WS ( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKS$OPEN_WS( WISS, GKS$K_CONID_DEFAULT, 
* GKSSK_WSTYPE_WISS ) 
Cc Only activate the WISS workstation. 
Yt] CALL GKS$ACTIVATE_WS( WISS ) 
Cc Create two segments and store them on the WISS workstation. 
CALL GKS$SET_VIEWPORT( LOWER_LEFT CORNER, 0.0, 0.5, 0.0, 0.5 ) 
CALL GKS$SET_VIEWPORT( UPPER_LEFT CORNER, 0.0, 0.5, 0.5, 1.0 ) 
CALL GKS$CREATE_SEG( HOUSE } 
CALL GKS$SELECT_XFORM( LOWER_LEFT_CORNER ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG() 
CALL GKS$CREATE_SEG( TITLE ) 
CALL GKS$SELECT_XFORM( UPPER_LEFT CORNER ) 
CALL GKS$SET_TEXT HEIGHT ( LARGER ) 
CALL GKS$TEXT( WORLD_X, WORLD_Y, ‘Associated segment.’ ) 
CALL GKS$CLOSE_SEG() 
CALL GKSS$ACTIVATE_WS( WS_ID ) 
Cc Associate the text with the VT241, but only copy the house. 
@ CALL GKS$ASSOC_SEG_WITH_WS( WS_ID, TITLE ) 


CALL GKS$COPY_SEG TO WS( WS_ID, HOUSE ) 


(continued on next page) 
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Example 8—1 (Cont.): Comparing ASSOCIATE SEGMENT WITH 


WORKSTATION and COPY SEGMENT TO 
WORKSTATION 


Release deferred output. Pause. Type RETURN when you are finished 
viewing the picture. 

CALL GKS$UPDATE WS( WS_ID, GKSS$K_POSTPONE FLAG ) 

READ (5, *) 


Redraw all segments forcing an update to the screen. 
CALL GKSSREDRAW_ SEG _ON_WS( WS_ID ) 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKSS$DEACTIVATE_WS( WISS ) 
CALL GKS$CLOSE_WS( WISS )_ 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 
@ If you activate only the WISS workstation, DEC GKS stores created 


segments only on the WISS workstation. The VT241 screen remains 
clear. 


By associating the segment containing text, the VT241 stores the seg- 
ment. By copying the segment containing the house, DEC GKS draws 
the primitives to the VT241 screen, but the VT241 does not store the 

segment. 


When you redraw all segments, you force DEC GKS to update the 
screen, eliminating all primitives not contained in segments. The house 
disappears and the text remains on the VT241 since it is stored as a 
segment. 


Figure 8—3 shows the screen of a VT241 terminal after the program has run 
to completion. 
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Figure 8-3: Comparing ASSOCIATE SEGMENT WITH WORKSTATION and 
COPY SEGMENT TO WORKSTATION—VT241 


adaneiated sagvent. 
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8.3 Segments and Surface Update 


When you request changes to segment attributes (described in Section 8.4), 
the change may take place immediately (dynamically) or DEC GKS 

may need to update the surface to implement the change (an implicit 
regeneration), depending on the capabilities of your device. An implicit 
regeneration clears the screen and only redraws the primitives stored 

in segments. All segments not stored in primitives are lost. You can 

use the function INQUIRE DYNAMIC MODIFICATION OF SEGMENT 
ATTRIBUTES to determine if a request for a segment attribute change 
requires an implicit regeneration on your device. 


There are two ways to determine whether your device requires an implicit 
regeneration to implement a change. If you are making only a few changes, 
you can call INQUIRE WORKSTATION DEFERRAL AND UPDATE 
STATES to determine if the new frame necessary at update flag is YES. If 
you are making many different changes, calling INQUIRE WORKSTATION 
DEFERRAL AND UPDATE STATES each time is inefficient. 
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You can call INQUIRE DYNAMIC MODIFICATION OF SEGMENT 
ATTRIBUTES once to determine for which changes your workstation 
requires an implicit regeneration. Then, you can set flags to force regen- 
erations only when you make changes that require them. If you need to 
regenerate the picture on the workstation surface when changing segment 
attributes, you simply call UPDATE WORKSTATION and pass 
GKS$K_PERFORM_FLAG as an argument. 


NOTE 


If you want to redraw all the segments on the workstation surface 
regardless of the current status of the new frame flag, you can call 
REDRAW ALL SEGMENTS ON WORKSTATION. A call to this 
function is equivalent to a call to UPDATE WORKSTATION while 
the new frame flag is set to YES, and while passing the argument 
GKS$K_PERFORM_FLAG. 


The following requests for changes to segments may require an implicit 
regeneration of the screen depending on the capabilities of your device (see 
Section 8.4 for a complete description of the segment attributes): 


Change Possible Effect 
Segment priority If you call the following functions: 


¢ ASSOCIATE SEGMENT WITH WORKSTATION 
¢ DELETE SEGMENT 

e¢ DELETE SEGMENT FROM WORKSTATION 

¢ SET SEGMENT PRIORITY 

e¢ SET SEGMENT TRANSFORMATION 

e SET VISIBILITY 

You may have created a situation in which two seg- 
ments of different priorities overlap, or in which an 
overlapped segment must now be made completely 
visible, or in which visibility changes. In all cases, 
DEC GKS must take the segments’ priorities into con- 
sideration before determining if the picture is out of 
date. 


Segment transformation Many workstations are unable to reposition segments 
dynamically, thus requiring an implicit regeneration. 
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Change Possible Effect 


Segment visibility Some workstations may be able to make an invisible 
segment visible dynamically, but may need an implicit 
regeneration to make visible segments invisible, since 
visible-to-invisible changes require that the segments 
“beneath” the segment be redrawn. Some workstations 
may need an implicit regeneration to perform both, and 
some workstations may be able to make both changes 
dynamically. 

Segment highlighting Some workstations may need to implicitly regenerate 
the surface before they can highlight a segment. 

Segment deletion Segment deletion may require reproducing the seg- 
ments “beneath” the deleted segment. Calling either 
DELETE SEGMENT or DELETE SEGMENT FROM 
WORKSTATION can require an implicit regeneration 
of the screen, depending on the capabilities of your 
workstation. 


There are other conditions under which DEC GKS may require a surface 
regeneration, depending on the capabilities of your device. For example, if 
you attempt to alter the polyline representation (refer to Chapter 5, Output 
Attribute Functions), the VT241 requires an implicit regeneration to affect 
this change. 


Therefore, if you are going to make certain output attribute changes 

or workstation transformation changes, you need to put all important 
output primitives into segments so that they are not lost when you update 
the surface. For complete information as to changes that may require 
implicit regeneration on UPDATE WORKSTATION, or on REDRAW ALL 
SEGMENTS ON WORKSTATION, refer to Chapter 3, Control Functions. 


8.4 Segment Attributes 


Just as a workstation stores the output attributes of a primitive when it is a 
part of a segment, a workstation stores segment attributes that affect all the 
primitives stored within a segment. The segment attributes are as follows: 


¢ Detectability 
¢ Highlighting 
¢ = Priority 
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e Transformation 
¢ Visibility 


The following sections describe the segment attributes in detail. 


8.4.1 Detectability 


This segment attribute determines whether or not the segment can be 
chosen during pick input. Pick input is only available on GKS$K_WSCAT_ 
OUTIN workstations. By default, DEC GKS segments are undetectable 
(GKS$K_UNDETECTABLE). 


In order for you to pick a segment, it must be both detectable and visible 
(GKS$K_VISIBLE). In many applications, if you do not want the user to 
be able to pick a segment, you should make the segment invisible as well 
as undetectable. Remember that making a segment undetectable does not 
make the segment invisible; these are two separate segment attributes. 


For more information concerning detectability, refer to SET DETECTABILITY 
in this chapter. For more information concerning pick input, refer to 
Chapter 7, Input Functions. 


8.4.2 Highlighting 


This segment attribute determines whether or not a workstation presents a 
highlighted segment on the workstation surface to draw the attention of the 
user to that segment. By default, DEC GKS segments are not highlighted 
(GKS$K_NORMAL). 


Highlighting is device dependent and can be implemented in any of the 
following ways: 

¢ Blinking all primitives in a segment 

¢ Outlining the segment extent rectangle 


e Reversing the foreground and background colors within the segment 
extent rectangle 


¢ Outlining of all output primitives stored within the segment 


The segment extent rectangle is the rectangle that outlines all the NDC 
points of the primitives stored in the segment. For more information 
concerning highlighting, refer to SET HIGHLIGHTING in this chapter. 
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8.4.3 Priority 


This segment attribute determines which segment’s primitives take priority 
when two segments overlap on the workstation surface. To assign a priority 
to a segment, you assign to the segment a real number greater than or equal 
to the value 0.0, and less than or equal to the value 1.0. Segments with the 
priority 0.0 have the lowest priority, and segments with the priority 1.0 have 
the highest priority. By default, DEC GKS segments have a priority value 
of 0.0. 


Different devices implement segment priority differently. Either a device 
supports an infinite number of priorities (theoretically), or the device 
supports a specific number of priorities. If the device supports an infinite 
amount of priorities, the maximum number of segment priorities supported 
entry in the workstation description table is the value 0. Otherwise, the 
entry contains the number of priorities supported. (To access this table 
entry, call the function INQUIRE SEGMENT PRIORITY.) 


If the number of priorities supported is not 0 (specifying an infinite number 
of supported priorities), then DEC GKS divides the 0.0 to 1.0 priority range 
into subranges according to the number of supported priorities. If you 
specify, for two different segments, two different priority values that fall 
within the same subrange, those segments have the same priority. For 
instance, if a workstation supports two segment priorities, all segments with 
the specified values between 0.0 and 0.5 inclusive have the same priority, 
and values between 0.51 and 1.0 have the same priority. 


For more information concerning segment priority, refer to SET SEGMENT 
PRIORITY in this chapter. 


8.4.4 Transformation 


When DEC GKS creates a picture containing segments, it places into effect 
the current normalization transformation, applies the current segment 
transformation to each segment, and if you have enabled clipping, clips 
the picture at the current normalization viewport. By default, DEC GKS 
applies the identity segment transformation to all segments. The identity 
transformation makes no changes to the size or position of the segment. 


If you desire, you can change the segment transformation that affects the 
following components of segment appearance. 
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Component 
Scaling 


Rotation 


Translation 


Description 


The first step in the segment transformation process is to scale 
the segment. Scaling determines the size of the segment extent 
rectangle, either enlarging or decreasing the total size of the 
segment. 


The second step in the segment transformation process is to rotate 
the segment. Rotation determines the positioning of the segment 
by establishing a fixed coordinate point in the segment, and then 
rotating the remaining segment points around the fixed point axis 
by a specified number of radians. 


The last step in the segment transformation process is to translate 
the segment’s coordinate points to new points according to vector 
coordinate values. Simply, it shifts the segment position in NDC 
space. 


Figure 8—4 illustrates the effects of scaling, rotation, and translation. 
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Figure 8-4: Scaling, Rotation, and Translation 


All points are NDC points 
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The first decision you must make when working with segment transforma- 
tions is whether to specify your fixed point in a world or NDC coordinate 
point. If you want to transform portions of the segment according to the 
current normalization transformation mapping, specify world coordinates. 
DEC GKS maps the specified world coordinate point to the NDC plane and 
then performs the rotation or scaling. 


If you want to transform the segment as stored on the NDC space (regard- 
less of the current normalization transformation), specify an NDC point as 
your fixed point. 


Next, if you want to scale or to rotate the segment, you must decide which 
point in the segment to use as an axis, or a fixed point. When DEC GKS 
scales the segment, the fixed point is the only point that maintains its 
position as the segment decreases or increases in size either towards or 
away from the fixed point. When DEC GKS rotates the segment, it uses the 
fixed point as the axis around which the other points in the segment rotate. 
If you do not wish to scale or rotate the segment, you can specify the value 
0.0 for both fixed point coordinate values. 


If you decide to shift the segment, you need to establish a translation vector. 
The translation vector is expressed by two real number values that specify 
by how much the X and Y segment coordinate values change. When DEC 
GKS translates the segment, it adds the values specified in the translation 
vector to the segment’s X and Y values, moving the segment within the 
specified coordinate plane. If you do not wish to translate the segment’s 
position, you can specify the value 0.0 for both components of the translation 
vector. 


If you decide to rotate the segment, you must decide on an angle of rotation 
in radians. A radian is a measure of an angle. A full circle, 360 degrees, 
equals 2*pi radians, one radian equaling 180/pi degrees. The value pi equals 
approximately 3.14. DEC GKS rotates the segment on the axis of the fixed 
point by the radian specified as the angle of rotation. Positive rotation 
values rotate counter clockwise; negative rotation values rotate clockwise. If 
you do not wish to rotate the segment, you can specify 0.0 for the angle of 
rotation. 


Finally, if you decide to scale the segment, you need to establish the scale 
factors. You express a scale factor as two real number values; DEC GKS 
multiplies the X and Y segment coordinate values by the scale factor com- 
ponents to determine the new size of the segment. If you do not want to 
scale the segment (keeping the segment the same size), specify the value 1.0 
for both components of the scale factor. Values less than 1.0 decrease the 
segment size, and values greater than 1.0 increase the segment size. 
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Once you have decided how to scale, rotate, and translate a segment, you 
must construct a transformation matrix. A transformation matrix is a 
six-element array of real values. To assist you in the creation of a trans- 
formation matrix, DEC GKS provides the utility functions EVALUATE 
TRANSFORMATION MATRIX and ACCUMULATE TRANSFORMATION 
MATRIX. The function EVALUATE TRANSFORMATION MATRIX has the 
following function syntax: 


GKS$EVAL_XFORM_MATRIX ( fixed_point_x, fixed_point_y, translation_vec_x, 
translation_vec_y, rotation, scale_x, scale_y, type_of_coordinates, 
transformation_mairix ) 


After evaluating the first eight arguments, EVALUATE TRANSFORMATION 
MATRIX establishes the appropriate transformation matrix and writes 

the six-element array of real numbers to the last argument transforma- 
tion_matrix. For detailed information concerning this function, refer to 
EVALUATE TRANSFORMATION MATRIX in this chapter. 


The function ACCUMULATE TRANSFORMATION MATRIX is identical to 
EVALUATE TRANSFORMATION MATRIX, except that its first read-only 


argument is another transformation matrix, as follows: 


GKS$ACCUM_XFORM_MATRIX { first_xform_matrix, fixed_point_x, fixed_point_y, 
translation_vec_x, translation_vec_y, rotation, scale_x, scale_y, type_of_coordinates, 
accumulated_xform_matrix ) 


If you have a previously constructed transformation matrix to which 
you want to add translation, shifting, and scaling values, you call 
ACCUMULATE TRANSFORMATION MATRIX. DEC GKS creates a 
new transformation matrix using the first matrix and the specified scal- 
ing, rotation, and translation information, and then returns the resulting 
transformation matrix to the last argument. 


Once you have established the desired transformation matrix, either by 
accumulating matrixes or by evaluating a single matrix, you can set the 
segment transformation using SET SEGMENT TRANSFORMATION, which 
takes the name of a segment and the transformation matrix identifier as its 
arguments. DEC GKS applies the specified transformation to the stored seg- 
ment on the NDC plane. This current transformation remains in effect until 
you change it. Before copying a segment, associating a segment, or inserting 
a segment on a workstation, DEC GKS first checks the current segment 
transformation in the segment state list, and applies that transformation to 
the stored segment. 


You may have to update the workstation surface in order to see the change 
in the segment transformation. See Section 8.3 for more information con- 
cerning surface update. , 
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To illustrate the entire process of segment transformation, review the 
following sequence of examples and figures. 


In Example 8-2, all the coordinate values are world coordinates. The fixed 
point is the tip of the house (0.25, 0.9). The translation vector represents 
the number of X and Y values by which we want to increase or decrease the 
present coordinates; in this example, the Y values increase by two world 
coordinate point units (0.0, 0.2). The angle of rotation is 30 degrees (pi/6 
radians). The scale factors represent a 50 percent decrease in size for both 
the X and Y axes (0.5, 0.5). 


If we specify all the necessary arguments in a single call to EVALUATE 
TRANSFORMATION MATRIX, DEC GKS always scales, then rotates, 
and finally translates the segment, in that order. Following the example, 
Figure 8-5 illustrates the effects of the example on a VT241. 


Example 8-2: The Effects of a Segment Transformation 


Cc This program transforms the house contained in a segment. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, LOWER_LEFT CORNER, HOUSE, NUM _POINTS 
REAL FIXED X, FIXED _Y, VECTOR_X, VECTOR_Y, ROTATION, 
* SCALE X, SCALE_Y, NULL, XFORM MATRIX( 6 ) 
REAL PX ( 9 ), PY ( 9) 
DATA FIXED_X / 0.25 / FIXED _Y / 0.9 /, VECTOR_X / 0.0 /, 
* VECTOR_Y / 0.2 /, SCALE_X / 0.5 /, SCALE_Y / 0.5 /, 
* NULL / 0.0 /, NUM_POINTS / 9 /, LOWER_LEFT_CORNER / 1 /, 
* HOUSE / 1 /, WS_ID / 1 / 
DATA PX / .4, .1, .1, .4, .25, .1, .4, .4, .1 / 
DATA PY -/- 21,0 slp e7y ote 8 9e” OT ope eT 


CALL GKSS$OPEN_GKS( ‘SYS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_ DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


CALL GKS$SET_VIEWPORT( LOWER_LEFT CORNER, 0.0, 0.5, 0.0, 0.5 ) 
CALL GKS$SELECT_XFORM( LOWER_LEFT CORNER ) 
CALL GKS$SET_CLIPPING( GKS$K_NOCLIP ) 


CALL GKS$CREATE_SEG( HOUSE ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG() 


(continued on next page) 
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Example 8-2 (Cont.): The Effects of a Segment Transformation 


c Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE FLAG ) 

READ (5, *) 
Cc Rotation equals pi divided by 6 (30 degrees). 


ROTATION = 3.14/6.0 


c Set scaling, rotation, and translation. 
1] CALL GKS$EVAL_XFORM_MATRIX( FIXED_X, FIXED _Y, VECTOR_X, 
* VECTOR_Y, ROTATION, SCALE X, SCALE Y,— 
* GKS$K_COORDINATES_WC, XFORM MATRIX ) 


C Transform the segment. 
2] CALL GKS$SET_SEG_XFORM( HOUSE, XFORM_MATRIX ) 

C Update the screen to show the transformed house. 
3) CALL GKS$UPDATE_WS( WS_ID, GKS$K_PERFORM FLAG ) 


CALL GKS$DEACTIVATE WS( WS ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKSS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ This call selects a normalization transformation with the new viewport. 
DEC GKS transforms all output in segments to the new viewport. For 
the existence of the segment, the segment’s primitives are clipped at this 
viewport boundary. 


@ Using a VT241, you cannot dynamically alter the segment currently 
displayed on the workstation surface by calling SET SEGMENT 
TRANSFORMATION. Calling this function at this point in the pro- 
gram changes the segment transformation in the segment state list, and 
sets flags in the workstation state list telling DEC GKS that the surface 
is out of date and that an update is necessary. 


© Calling UPDATE WORKSTATION updates the position of the image on 
the workstation surface. The function REDRAW ALL SEGMENTS ON 
WORKSTATION accomplishes the same task. Using both functions, all 
output not contained in segments is lost. 
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Figure 8—5 shows the screen of a VT241 terminal after the program has run 
to completion. 


Figure 8-5: The Effects of a Segment Transformation—VT241 
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In some applications, you may want to have more control over the order 
in which DEC GKS transforms segments. Simply, you may want to trans- 
form the segment in some other order besides scaling, then rotating, and 
finally translation. You can accomplish this task by calling ACCUMULATE 
TRANSFORMATION MATRIX. 


For example, you may wish to translate, then scale, and finally rotate the 
segment. Assuming all the variable declarations of the last code example, 
review the following code. 
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Cc To change the normal transformation order, set the translation... 
CALL GKS$EVAL_XFORM_MATRIX( NULL, NULL, VECTOR_X, 
* VECTOR_Y, NULL, 1.0, 1.0, 
* GKSS$K_COORDINATES WC, XFORM MATRIX 1 ) 


Cc Accumulate the scaling... , 
CALL GKS$ACCUM_XFORM MATRIX( XFORM_MATRIX_1, FIXED_X, FIXED_Y, 
* NULL, NULL, NULL, SCALE_X, SCALE_Y, GKS$K_COORDINATES WC, 
* XFORM MATRIX 2 ) 


Cc And add the rotation... 
CALL GKS$ACCUM_XFORM_MATRIX( XFORM_MATRIX_2, FIXED_X, FIXED_Y, 
* NULL, NULL, ROTATION, 1.0, 1.0, GKS$K_COORDINATES WC, 
* XFORM MATRIX 3 ) 


If you pass all three values to EVALUATE TRANSFORMATION MATRIX, 
DEC GKS scales, then rotates, and finally translates. Using the two calls 
to ACCUMULATE TRANSFORMATION MATRIX, you force DEC GKS to 
translate, scale, and then rotate the segment, in that order. 


8.4.4.1 Normalization and Segment Transformations, and Clipping 


When you generate an output primitive during segment creation, DEC 
GKS stores the primitive, the currently associated output attributes, the 
current clipping rectangle (the current normalization viewport), and the pick 
identifier value (refer to Section 8.1.1). 


When DEC GKS generates one of the primitives in a given segment, the 
primitive is transformed by the current normalization transformation, then 
the primitive is transformed by the specified segment transformation, and 
finally, if clipping was enabled before you generated the segment primitive 
(the default clipping status), the primitive is clipped at the stored normaliza- 
tion viewport boundary, not necessarily the current normalization viewport 
boundary. 


If clipping is not enabled at the time you generate an output primitive dur- 
ing segment creation, DEC GKS stores the default normalization viewport 
([0,1] x [0,1]) as the clipping rectangle for the generated primitive. 
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Consequently, when you translate a segment’s position using EVALUATE 
TRANSFORMATION MATRIX or ACCUMULATE TRANSFORMATION 
MATRIX, and if the segment crosses the viewport boundary, whether DEC 
GKS clips the primitives depends on the status of the clipping flag at the 
time of primitive generation. 


Example 8—3 implements the normalization transformation, implements 
the segment transformation, and then clips the segment at the viewport 
boundary. Following the program example, Figure 8-6 illustrates the effects 
of the example on a VT241. 


Example 8-3: Segment Transformations and Clipping 


aang 


aaa 


This program transforms the house contained in a segment and 
clips it at the stored normalization viewport (clipping 
rectangle). 

IMPLICIT NONE 

INCLUDE ’SYS$LIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, LOWER_LEFT CORNER, HOUSE, NUM_POINTS 
REAL VECTOR_Y, NULL, XFORM_MATRIX( 6 ), NO CHANGE 

REAL PX ( 9 ), PY (9 ) 

DATA VECTOR_Y / 0.1 /, NULL / 0.0 / 

DATA PX / .4, .1, .1, .4, .25, .1, .4, 1.4, .1 / 

DATA PY / .1, .1, «7, «7, «9, «7, «1, «7, 21 / 

DATA NUM_POINTS / 9 /, LOWER_LEFT_CORNER / 1 /, 
* HOUSE / 1 /, NO_CHANGE / 1.0 /, WS_ID / 1 / 


CALL GKSSOPEN_GKS( 'SYS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKSS$K_VT240 ) 
CALL GKSSACTIVATE_WS( WS_ID ) 


Set the clipping boundary to be the lower left corner of the 
default normalization viewport. 

CALL GKS$SET_VIEWPORT( LOWER_LEFT_CORNER, 0.0, 0.5, 0.0, 0.5 ) 
CALL GKS$SELECT_XFORM({ LOWER_LEFT_CORNER ) 

Even though clipping is the default, specify it to be clear. 
CALL GKSSSET_CLIPPING( GKSS$K_CLIP ) 


CALL GKS$CREATE SEG( HOUSE ) 
CALL GKSS$POLYLINE( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG() 


Set the current clipping rectangle to be the unity normalization 
viewport ([0,1] X [0,1]). DEC GKS uses the stored viewport (lower 
left corner), not this viewport, to clip the segment primitive. 
CALL GKS$SELECT_XFORM( 0 ) 


(continued on next page) 
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Example 8-3 (Cont.): Segment Transformations and Clipping 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 
CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 
READ (5, *) 
c Translate the house’s position upwards by 1 world coordinate. 
3) CALL GKSS$EVAL_XFORM MATRIX( NULL, NULL, NULL, 


* VECTOR_Y, NULL, NO_CHANGE, NO CHANGE, 
* GKS$K_COORDINATES WC, XFORM MATRIX ) 


Cc Transform the segment and update the screen. 
CALL GKS$SET_SEG_XFORM( HOUSE, XFORM_MATRIX ) 
CALL GKSS$UPDATE_WS( WS_ID, GKS$K_PERFORM FLAG ) 


Cc Pause. Type RETURN when you are finished viewing the picture. 
READ (5, *) 
Cc Translate the house’s position upwards by 1 world coordinate. 


CALL GKS$ACCUM_XFORM MATRIX ( XFORM MATRIX, NULL, NULL, 
* NULL, VECTOR_Y, NULL, NO_CHANGE, NO_CHANGE, 
* GKS$K COORDINATES WC, XFORM MATRIX ) 


Cc Transform the segment and update the screen. 
CALL GKS$SET_SEG_XFORM( HOUSE, XFORM_MATRIX ) 
CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM FLAG ) 


c Pause. Type RETURN when you are finished viewing the picture. 
READ (5, *) 
Cc Again, translate the house’s position upwards by 1 world coordinate. 


CALL GKSSACCUM_XFORM_MATRIX( XFORM_MATRIX, NULL, NULL, 
* NULL, VECTOR_Y, NULL, NO_CHANGE, NO_CHANGE, 
* GKS$K_COORDINATES_WC, XFORM_ MATRIX ) 


Cc Transform the segment. 
CALL GKS$SET_SEG_XFORM( HOUSE, XFORM MATRIX ) 


c Update the surface to initiate the change. 
CALL GKSSUPDATE_WS( WS_ID, GKSSK_PERFORM_ FLAG ) 


CALL GKS$DEACTIVATE WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS() 

END 





The following numbers correspond to the numbers in the previous example: 


@ This call selects a normalization transformation with the new viewport. 
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@ Enabling clipping (the default setting) stores the new clipping window 
with any subsequently generated output primitives. 
Although this program generates only one output primitive, you can 
change the clipping flag every time you output a primitive depending on 
the needs of your application. The current clipping rectangle is bound to 
subsequently generated primitives until you change the rectangle. 


© This call to EVALUATE TRANSFORMATION MATRIX alters the Y 
translation component so that the top portion of the house extends past 
the clipping rectangle. 


On the VT241, you need to update the workstation surface to see changes in 
a segment transformation. Figure 8-6 shows the screen of a VT241 terminal 
after the program has run to completion. 


Figure 8-6: Segment Transformations and Clipping—VT241 
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During transformation, a segment’s primitives may exceed the default 
normalization viewport, defined as ([0,1] x [0,1]). DEC GKS can store 
segments that exceed the default normalization viewport in NDC space. 


However, even though DEC GKS can store segments that exceed the default 
normalization viewport boundary, those portions cannot be displayed on the 
surface of the workstation. DEC GKS clips all pictures at that workstation 
window boundary during the workstation transformation, and the maximum 
workstation window is ({0,1] x [0,1]) on the NDC plane. 


8.4.4.2 Implementing Multiple Transformations 


To understand the most complex combination of transformations, review the 
following code example: 


These lines of code insert one segment’s primitives into 
an open segment. 


CALL GKS$SELECT_XFORM( NORM ) 

CALL GKS$SET_SEG_XFORM( SEG_ONE, MATRIX ONE ) 
CALL GKS$SET_CLIPPING( GKS$K_CLIP ) 

CALL GKS$SET_SEG_XFORM( SEG TWO, MATRIX_TWO ) 


aa 


CALL GKS$CREATE SEG( SEG ONE ) 


CALL GKS$INSERT_SEG( SEG_TWO, MATRIX_THREE ) 
CALL CLOSE_SEG() 


In the previous example, there are four different transformations involved in 
the creation of the segment seg_one. DEC GKS implements those transfor- 
mations and clipping, in a cumulative fashion, in the following order: 


@ The first transformation that DEC GKS implements is always the 
current normalization transformation (norm). 


© Ifyou are inserting a segment from WISS, DEC GKS always implements 
the inserted segment’s transformation (matrix_two). 


© Again, if you are inserting a segment from WISS, DEC GKS always im- 
plements the transformation specified in the call to INSERT SEGMENT, 
which is called the insertion matrix (matrix_three). 


@ Lastly, DEC GKS implements the transformation of the created segment 
(matrix_one). 
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© After all normalization and segment transformations are implemented, 
DEC GKS clips at the normalization viewport stored with the primitives 
in seg_one (the viewport associated with norm). 


After the normalization and segment transformations, DEC GKS always 
applies a workstation transformation to the picture. DEC GKS clips all 
pictures at the workstation viewport boundary. 


Figure 8—7 illustrates the transformation and clipping pipeline. 
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Figure 8-7: The Transformation and Clipping Pipeline 
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8.4.5 Visibility 


This segment attribute determines if the segment is visible on the work- 
station surface. By default, DEC GKS segments are visible (GKS$K_ 
VISIBLE). 


Visibility can be used to hide a segment from a user until the segment 
is needed. For instance, segment visibility is a useful way to control the 
displaying of messages and menus, although MESSAGE and REQUEST 
CHOICE can perform the same task. 


By default, the visibility segment attribute is set to GKS$K_VISIBLE. Keep 
in mind that a segment must be both visible and detectable in order to pick 
that segment during pick input (refer to Chapter 7, Input Functions). 


8.5 Segment Inquiries 


The following list presents the inquiry functions that you can use to obtain 
segment information when writing device-independent code: 


INQUIRE CLIPPING 

INQUIRE DYNAMIC MODIFICATION OF SEGMENT ATTRIBUTES 
INQUIRE LEVEL OF GKS 

INQUIRE NAME OF OPEN SEGMENT 

INQUIRE OPERATING STATE VALUE 

INQUIRE PICK IDENTIFIER 

INQUIRE SEGMENT ATTRIBUTES 

INQUIRE SET OF ACTIVE WORKSTATION 

INQUIRE SET OF ASSOCIATED WORKSTATIONS 

INQUIRE SET OF OPEN WORKSTATIONS 

INQUIRE SET OF SEGMENT NAMES IN USE 

INQUIRE SET OF SEGMENT NAMES ON WORKSTATION 
INQUIRE WORKSTATION CATEGORY 

INQUIRE WORKSTATION DEFERRAL AND UPDATE STATES 
INQUIRE WORKSTATION MAXIMUM NUMBERS 

INQUIRE WORKSTATION STATE 

INQUIRE WORKSTATION TYPE 


For more information concerning device-independent programming, refer to 
the DEC GKS User Manual. © 
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8.6 Function Descriptions 


This section describes the DEC GKS segment functions in detail. 
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ACCUMULATE TRANSFORMATION MATRIX 


ACCUMULATE TRANSFORMATION MATRIX 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function ACCUMULATE TRANSFORMATION MATRIX accepts a 
specified transformation matrix, concatenates new segment transformation 
component values, and then writes the accumulated transformation to 

the last argument of the function. The only way to achieve a cumulative 
effect from successive segment transformations is to use ACCUMULATE 
TRANSFORMATION MATRIX. 


See Section 8.4.4.1 for a detailed description of segment transformation and 
transformation matrixes. 


GKS$ACCUM_XFORM_MATRIX (first_xform_matrix, 
fixed_point_x, fixed_point_y, 
translation_vec_x, 
translation_vec_y, 
rotation, scale_x, scale_y, 
type_of_coordinates, 
accumulated_xform_matrix) 


GACTM (matrix, fx, fy, x_vector, y_vector, rotate, scale_x, 
scale_y, wc_ndc, nmatrix) : 


gaccumtran (segtran, ppoint, pshift, angle, pscale, coord, result) 
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ACCUMULATE TRANSFORMATION MATRIX 


Arguments 


first_xform_matrix 


data type: array (real) 
access: read-only 
mechanism: by reference 


This argument is a six-element transformation matrix created previ- 

ously by a call to either EVALUATE TRANSFORMATION MATRIX or 
ACCUMULATE TRANSFORMATION MATRIX. You declare this argument 
as a six-element, single dimension array. 


fixed_point_x 


fixed_point_y 

data type: real 

access: - read-only 
mechanism: by reference 


These arguments are the coordinates of the fixed point, used as the axis 
point during segment scaling and rotation. You can express this point as 
a world coordinate point or as an NDC point depending on the value you 
passed to the argument type_of_coordinates. 


If you do not wish to scale or rotate the segment, you can pass the value 0.0 
for both arguments. 


translation_vec_x 
translation_vec_y 


data type: real 
access: read-only 
mechanism: by reference 


These arguments express the coordinate values to be added to all segment X 
and Y values in order to alter the position of the segment. You can express 
these values as world coordinate values or as NDC values depending on the 
value you passed to the argument type_of_coordinates. 


If you do not wish to translate the segment, you can pass the value 0.0 for 
both arguments. 
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ACCUMULATE TRANSFORMATION MATRIX 


rotation 

data type: real 

access: read-only 
mechanism: by reference 


This argument is the measure of the angle of segment rotation around the 
fixed-point axis, in radians. To calculate radians, use the formula 
360 degrees = 2*pi radians. 


If you do not wish to rotate the segment, you can pass the value 0.0 for this 
argument. 


scale_x 

scale_y 

data type: real 

access: read-only 
mechanism: by reference 


These arguments are the real number values that are multiplied times all 
the segment’s X and Y coordinates except the fixed point, to determine the 
new X and Y positions of the scaled segment. 


If you do not wish to scale the segment, you can pass the value 1.0 for these 
arguments. 


type_of_coordinates 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the flag that determines whether DEC GKS uses world 
coordinates or NDC coordinate values for the fixed point and translation 

vector arguments. This argument can be either of the following values or 
constants: 


Value Constant Description 

0 GKS$K_COORDINATES_WC The fixed point and translation vectors 
are world coordinate values. _ 

1 GKS$K_COORDINATES_NDC The fixed point and translation vectors 
are NDC values. 
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ACCUMULATE TRANSFORMATION MATRIX 


Use caution when specifying GKS$K_COORDINATES_WC. DEC GKS uses 
the current normalization transformation to transform the fixed point from 
world coordinates to NDC values. The current normalization transformation 
might not be the same as the one used during primitive generation. If 

the current normalization transformation is different, the result may be 
unexpected. 


accumulated_xform_matrix 


data type: array (real) 
access: write-only 
mechanism: by reference 


This argument is the six-element transformation matrix that results from 
the concatenation of the new scaling, rotation, and translation component 
values with the argument first_xform_matrix. You can use this value 

as an argument to SET SEGMENT TRANSFORMATION to establish 

a cumulative segment transformation. You declare this argument as a 
six-element, single-dimension array. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

8 GKS$_ERROR_8 GKS not in proper state: GKS 


shall be in one of the states GKOP, 
WSOP, WSAC, or SGOP in routine 


RE 


Program Example 


Example 8-4 illustrates the use of the function ACCUMULATE 
TRANSFORMATION MATRIX. Following the program example, Figure 8-8 
illustrates the program’s effect on a VT241 workstation. 
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ACCUMULATE TRANSFORMATION MATRIX 


Example 8-4: Showing the Cumulative Effect of ACCUMULATE 
TRANSFORMATION MATRIX 





Cc This program transforms the house contained in a segment. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, LOWER_LEFT CORNER, HOUSE, NUM_POINTS 
REAL VECTOR_Y, NULL, ~ XFORM | MATRIX( 6 ), NO! CHANGE 
REAL PX ( 9 ), PY ( 9.) 
DATA VECTOR_Y / 0.1 /, NULL / 0.0 / 
DATA PR /) 44y: dy: ody o4y- 625) wy oA dye olf 
DATA PY / .1, .1, .7, .7, .9, Tp deg cal pe; 22 tf 
DATA NUM_POINTS / 97, LOWER_LEFT CORNER / 1 /, 
* HOUSE / 1 /, NO_CHANGE / 1. O43 Ws_ID /1/ 


CALL GKSSOPEN_GKS( ’SYSSERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE_| WS( WS_ID ) 


CALL GKS$SET_VIEWPORT( LOWER_LEFT CORNER, 0.0, 0.5, 0.0, 0.5 ) 


0 CALL GKS$SELECT_XFORM( LOWER_LEFT CORNER ) 
CALL GKSS$SET_CLIPPING( GKSSK_NOCLIP ) 


CALL GKSS$CREATE_SEG( HOUSE ) 
CALL GKSSPOLYLINE( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG() 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKSSUPDATE_WS ( WS_ID, GKS$K_POSTPONE FLAG ) 

READ (5, *) 
C Shift the house upwards by 1 world coordinate. 


CALL GKS$EVAL_XFORM MATRIX( NULL, NULL, NULL, 
* VECTOR_Y, NULL, NO CHANGE, NO_CHANGE, 
* GKSS$K_COORDINATES WC, XFORM MATRIX ) 


Cc Transform the segment and update the screen. 
e CALL GKS$SET_SEG_XFORM( HOUSE, XFORM MATRIX ) 
3] CALL GKSS$UPDATE_WS( WS_ID, GKS$K_PERFORM_ FLAG ) 


(continued on next page) 
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ACCUMULATE TRANSFORMATION MATRIX 


Example 8-4 (Cont.): Showing the Cumulative Effect of ACCUMULATE 
TRANSFORMATION MATRIX 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 
CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 
READ (5, *) 
Cc Shift the house upwards by 1 more world coordinate. 
4) CALL GKSSACCUM_XFORM_MATRIX( XFORM MATRIX, NULL, NULL, 


* NULL, VECTOR_Y, NULL, NO CHANGE, NO CHANGE, 
* GKSS$K_COORDINATES WC, XFORM_ MATRIX ) 


Cc Transform the segment and update the screen. 
CALL GKS$SET_SEG_XFORM( HOUSE, XFORM MATRIX ) 
CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM FLAG ) 


Cc Release deferred output. Pause. Type RETURN when you are finished 
C viewing the picture. 

CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_ FLAG ) 

READ (5, *) 
C Again, shift the house upwards by 1 more world coordinate. 


CALL GKS$ACCUM_XFORM MATRIX( XFORM MATRIX, NULL, NULL, 
* NULL, VECTOR_Y, NULL, NO_CHANGE, NO_CHANGE, 
* GKS$K_COORDINATES WC, XFORM MATRIX ) 


Cc Transform the segment. 
CALL GKS$SET_SEG_XFORM( HOUSE, XFORM_MATRIX ) 


Cc Update the surface to initiate the change. 
CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM FLAG ) 


CALL GKS$DEACTIVATE WS( WS_ID ) 
CALL GKSS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ This call selects a normalization transformation with the new viewport. 
DEC GKS transforms all output in segments to the new viewport. 
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ACCUMULATE TRANSFORMATION MATRIX 


@ Using the VT241, you cannot dynamically alter the segment, cur- 
rently displayed on the workstation surface, by calling SET SEGMENT 
TRANSFORMATION. Calling this function at this point in the program 
changes the segment transformation in the segment state list, and sets 
flags in the workstation state list telling DEC GKS that the surface is 
out of date and that an update is necessary. 


© Calling UPDATE WORKSTATION updates the position of the image on 
the workstation surface. The function REDRAW ALL SEGMENTS ON 
WORKSTATION accomplishes the same task. Using both functions, all 
output not contained in segments is lost. 

@ Using ACCUMULATE TRANSFORMATION MATRIX, you can add 
transformation components to a previously set transformation. In this 


program, the house gradually moves upward, one Y world coordinate 
point at a time, using ACCUMULATE TRANSFORMATION MATRIX. 


Figure 8-8 shows the screen of a VT241 terminal after the program has run 
to completion. 
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ACCUMULATE TRANSFORMATION MATRIX 


Figure 8-8: The Cumulative Effect of ACCUMULATE TRANSFORMATION 
MATRIX—VT241 
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ASSOCIATE SEGMENT WITH WORKSTATION 


ASSOCIATE SEGMENT WITH WORKSTATION 


Operating States: WSOP, WSAC 


Description 


Syntax 


The function ASSOCIATE SEGMENT WITH WORKSTATION takes a 
segment stored in workstation independent segment storage (WISS), and 
stores the segment on the specified workstation. 


See Section 8.2 for more information concerning WISS. 


GKS$ASSOC_SEG_WITH_WS  (workstation_id, segment_name) 
GASGWK = (workstation_id, segment_name) — 
gassocsegws (workstation_id, segment_name) 


Arguments 


workstation_id 


data type: integer 

access: read-only 

mechanism: by reference 

This argument is the integer value associated with an open or active 
workstation. 


segment_name 


data type: integer 
_ access: read-only 
mechanism: by reference 


This argument is the integer value that identifies a segment that is stored 
on a WISS workstation. 
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ASSOCIATE SEGMENT WITH WORKSTATION 


Error Messages 


Error 
Number 


—20 


20 
25 
27 
33 
35 
120 


124 


Program Example 


Completion 
Status Code 
DECGKS$_ERROR_NEG_20 


GKS$_ERROR_6 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_27 
GKS$_ERROR_33 
GKS$_ERROR_35 
GKS$_ERROR_120 


GKS$_ERROR_124 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be either in the state WSOP 


or in the state WSAC in routine 
KEKE 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Workstation Independent Segment 
Storage is not open in routine **** 


Specified workstation is of cate- 
gory MI in routine **** 


Specified workstation is of cate- 
gory INPUT in routine **** 


Specified segment name is invalid 
in routine **** 


Specified segment does not exist 
on Workstation Independent 
Storage in routine **** 


Refer to Example 8—1 in this chapter for a program example using a call to 
ASSOCIATE SEGMENT WITH WORKSTATION. 


8-40 Segment Functions 


CLOSE SEGMENT 


Operating States: CLOSE SEGMENT 


Description 


CLOSE SEGMENT 


The function CLOSE SEGMENT closes a segment. After you call this 
function, you can no longer add output primitives to that segment. You 


cannot reopen a segment. 


Calling this function changes the DEC GKS operating state from GKS$K_ 
SGOP (segment open) to GKS$K_WSAC (at least one workstation active). 


Syntax 


GKS$CLOSE_ SEG /() 
GCLSG /() 
gcloseseg () 


Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
4 . GKS$_ERROR_4 


Message 
GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be in the state SGOP in 
routine **** 
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CLOSE SEGMENT 


| Program Example 


Example 8-5 illustrates the use of the function CLOSE SEGMENT. 
Following the program example, Figure 8—9 illustrates the effect of this 
example on a VT241. 


Example 8-5: Drawing a House and Placing It in a Segment 


1 


Cc This program draws a house in the lower left corner of the 
Cc screen. 
IMPLICIT NONE 
INCLUDE ’ SYS$LIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, LOWER_LEFT CORNER, HOUSE, NUM_POINTS 
REAL PX ( 9 ), PY (9 ) 
DATA PX / .4, .1, .1, .4, .25, .1, .4, .4, .1 / 
DATA PY / .1, .1, .7, .7, .9, ~.7, +1, .7, .1 / 
DATA NUM_POINTS / 9 /, LOWER_LEFT_CORNER / 1 /, 
* HOUSE / 1 /, WS_ID / 1 / 


CALL GKSSOPEN_GKS( '’SYSS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


CALL GKS$SET_VIEWPORT( LOWER_LEFT CORNER, 0.0, 0.5, 0.0, 0.5 ) 


CALL GKS$CREATE_SEG( HOUSE ) 

CALL GKS$SELECT_XFORM( LOWER_LEFT_ CORNER ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG() 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 
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Figure 8—9 shows the screen of a VT241 terminal after the program has run 
to completion. 


Figure 8-9: House in the Lower Left Corner of the Screen—VT241 
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COPY SEGMENT TO WORKSTATION 


Operating States: WSOP, WSAC 


Description 


The function COPY SEGMENT TO WORKSTATION takes a segment stored 
in workstation independent segment storage (WISS), transforms it according 
to its segment transformation, clips it according to the stored clipping 
rectangles for each primitive, and then copies its primitives to the specified 
workstation. The specified workstation does not store the primitives in a 
segment. 


See Section 8.2 for more information concerning WISS. 


Syntax 

GKS$COPY_SEG_TO_WS  (worksiation_id, segment_name) 

_GCSGWK  (workstation_id, segment_name) 

gcopysegws _ (workstation_id, segment_name) 
Arguments 

workstation_id 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the integer value associated with an open or active 
workstation. This value cannot be GKS$K_WSTYPE_WISS. 
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segment_name 


data type: 
access: 


mechanism: 


integer 
read-only 
by reference 


This argument is the integer value that identifies a segment. This segment 
must be stored on a WISS workstation. 


Error Messages 


Error 
Number 


20 
25 
27 
33 


35 


Completion 
Status Code 
DECGKS$_ERROR_NEG_20 
DECGKS$_ERROR_NEG_94 


GKS$_ERROR_6 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_27 
GKS$_ERROR_33 


GKS$_ERROR_35 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


Internal GKS error: Corrupted 
segment memory in routine **** 


GKS not in proper state: GKS | 
shall be either in the state WSOP 


or in the state WSAC in routine 
we 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Workstation Independent Segment 
Storage is not open in routine **** 


Specified workstation is of cate- 
gory MI in routine **** 


Specified workstation is of cate- 
gory INPUT in routine **** 
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Error Completion 

Number Status Code Message 

36 GKS$_ERROR_36 Specified workstation is of cat- 
egory Workstation Independent 
Segment Storage in routine **** 

120 GKS$_ERROR_120 Specified segment name is invalid 
in routine **** 

124 GKS$_ERROR_124 Specified segment does not exist 


on Workstation Independent 
Storage in routine **** 


Program Example 


Refer to Example 8~1 in this chapter for a program example using a call to 
COPY SEGMENT TO WORKSTATION. 
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CREATE SEGMENT 


Operating States: WSCA 


Description 


Syntax 


The function CREATE SEGMENT opens a segment on all active worksta- 
tions and names that segment. All subsequent calls to output functions add 
output primitives to the segment until you call CLOSE SEGMENT. DEC 
GKS stores output primitives, output attributes, and the current clipping 
rectangle for each of the primitives. You cannot nest a call to CREATE 
SEGMENT within the creation of another segment. See Section 8.1 for more 
information. 


DEC GKS must be in the GKS$K_WSAC (at least one workstation active) 
operating state to call this function. After calling CREATE SEGMENT, the 
operating state changes from GKS$K_WSAC to GKS$K_SGOP (segment 
open). 


GKS$CREATE_SEG (segment_name) 
GCRSG (segment_name) 
gcreateseg (segment_name) 


Segment Functions 8—47 


CREATE SEGMENT 


Arguments 
segment_name 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the integer value that identifies a stored segment. You 
cannot use the same identifier to name two different segments. Using DEC 
GKS, you must use positive integers as segment names. 


Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
3 GKS$_ERROR_3 

120 GKS$_ERROR_120 

121 GKS$_ERROR_121 


Program Example 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be in the state WSAC in 
routine **** 

Specified segment name is invalid 
in routine **** 


Specified segment name is already 
in use in routine **** 


Refer to Example 8—5 in this chapter for a program example using a call to 


CREATE SEGMENT. 
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DELETE SEGMENT 


Operating States: WSOP, WSAC, SGOP 
Description 


The function DELETE SEGMENT deletes the specified segment from all 
workstations storing that segment. You can delete any defined segment, but 
_you cannot delete an open segment. 


Calling this function deletes the specified segment’s state list. 


Syntax 

GKS$DELETE_SEG (segment_name) 

GDSG (segment_name) 

gdelseg (segment_name) 
Arguments 

segment_name 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the integer value that identifies a stored segment. 
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Error Messages 


120 
122 


125 


Program Example 


Completion 
Status Code 
DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_120 
GKS$_ERROR_122 


GKS$_ERROR_125 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 
Specified segment name is invalid 
in routine **** 

Specified segment does not exist in 
routine **** 

Specified segment is open in 
routine **** 


Example 8-6 illustrates the use of the function DELETE SEGMENT. 
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Example 8-6: Deleting Segments on All Open and Active Workstations 


Cc This program draws a house in the lower left corner of the 
Cc screen and then deletes it. 
IMPLICIT NONE 
INCLUDE ’SYSS$LIBRARY :GKSDEFS.FOR’ 
INTEGER WS_ID, LOWER_LEFT CORNER, HOUSE, WISS, 
* NUM_POINTS 
REAL PX ( 9 ), PY (9 ) 
DATA PX / .4, .1, .1, .4, .25, .1, .4, .4, .1 / 
DATA PY / .1, .1, .7, «7, -9, «7, «1, «7, 21 / 
DATA NUM_POINTS / 9 /, LOWER_LEFT_CORNER / 1 /, 
* HOUSE / 1 /, WISS / 2 /, WS __ “ID / 1 / 


CALL GKSSOPEN_GKS( 'SYS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_ DEFAULT, GKS$K_VT240 ) 


© CALL GKSSOPEN_WS( WISS, GKSS$K_ CONID ) DEFAULT, 
* GKSS$K_WSTYPE_WISS ) 


CALL GKSSACTIVATE_WS( WISS ) 
CALL GKSSACTIVATE_WS( WS_ID ) 


CALL GKS$SET_VIEWPORT( LOWER_LEFT_CORNER, 0.0, 0.5, 0.0, 0.5 ) 


Cc DEC GKS stores this segment on WS_ID and the WISS workstation. 
CALL GKS$CREATE_SEG( HOUSE ) 
CALL GKS$SELECT_XFORM( LOWER_LEFT_ CORNER ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 


Cc Close the currently open segment. 
CALL GKS$CLOSE_SEG() 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 
CALL GKSSUPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 
READ (5, *) 
Cc Delete the segment from all open and active workstations. 
@ CALL GKS$DELETE_SEG( HOUSE ) 
Cc You have to update the screen to delete the output primitives 
Cc from the surface. 


CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM_ FLAG ) 
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Example 8-6 (Cont.): Deleting Segments on All Open and Active 
Workstations 


CALL GKSSDEACTIVATE_WS( WS_ID ) 
CALL GKSSCLOSE_WS( WS_ID ) 
CALL GKSSDEACTIVATE_WS( WISS ) 
CALL GKS$CLOSE_WS( WISS ) 

.CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ This line of code opens a WISS workstation. From this point forward, 
anytime DEC GKS stores output in a segment on the VT241, it stores 
the same output in the same segment on the WISS workstation. 


@ After this line of code is executed, you cannot copy the segment house 
from the WISS workstation to the workstation ws_id, since this line 
deletes the segment from all workstations. 
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DELETE SEGMENT FROM WORKSTATION 


Operating States: WSOP, WSAC, SGOP 
Description 


The function DELETE SEGMENT FROM WORKSTATION deletes the 
segment from the specified workstation storing that segment. You can delete 
any defined segment, but you cannot delete an open segment. 


If you delete the segment from the last workstation supporting a given 
segment, calling this function deletes the specified segment’s state list, 
which has the same effect as a call to the function DELETE SEGMENT. 


Syntax 
GKS$DELETE_SEG_FROM_WS _§ (workstation_id, 
segment_name) 
GDSGWK_ (workstation_id, segment_name) 
gdelsegws_ (workstation_id, segment_name) 
Arguments 
workstation_id 
data type: integer 
access: read-only 
- mechanism: by reference 
This argument is the integer value associated with an open or active 
workstation. 
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segment_name 


data type: 
access: 


mechanism: 


integer 
read-only 
by reference 


This argument is the integer value that identifies a stored segment. 


Error Messages 


Error 
Number 


—20 


20 
25 
33 
35 
120 


123 


125 
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Completion 
Status Code 


DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_33 
GKS$_ERROR_35 
GKS$_ERROR_120 


GKS$_ERROR_123 


GKS$_ERROR_125 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 
GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is of cate- 
gory MI in routine **** 


Specified workstation is of cate- 
gory INPUT in routine **** 


Specified segment name is invalid 
in routine **** 


Specified segment does not exist 


on specified workstation in routine 
oho 


Specified segment is open in 
routine **** 


DELETE SEGMENT FROM WORKSTATION 


Program Example 


Example 8—7 illustrates the use of the function DELETE SEGMENT FROM 
WORKSTATION. 


Example 8-7: Deleting Segments on a Specific Workstation | 





Cc This program draws a house in the lower left corner of the 
C screen and then deletes it from the VT24l1. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, LOWER_LEFT CORNER, HOUSE, WISS, 
* NUM_POINTS 
REAL PX ( 9 ), PY (9 ) 
DATA PX 7° 4, «ly, sy «4p a25% ody 049. cap 21 7 
DATA PY / c1,. ely Tp 2 Ty. -3 9". 2 Te cde 6Ty. 217 
DATA NUM_POINTS / 9 /, LOWER_LEFT_CORNER / 1 /, 
* HOUSE / 1 /, WISS / 2 /, WS_ID / 1 / 


CALL GKS$OPEN. GKS( ‘SYS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 


0 CALL GKSSOPEN_WS( WISS, GKS$K_CONID_DEFAULT, 
* GKSS$K_WSTYPE WISS ) 


CALL GKS$ACTIVATE _WS( WISS ) 
_CALL GKSSACTIVATE_WS( WS_ID ) 


CALL GKS$SET_VIEWPORT( LOWER_LEFT CORNER, 0.0, 0.5, 0.0, 0.5 ) 
CALL GKS$SELECT_XFORM( LOWER_LEFT_ CORNER ) 


c DEC GKS stores this segment on WS_ID and the WISS workstation. 
CALL GKS$CREATE_SEG( HOUSE ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 
CALL GKSS$CLOSE_SEG() 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 
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Example 8-7 (Cont.): Deleting Segments on a Specific Workstation 


C Delete the segment from WS_ID and update the screen. 
2] CALL GKS$DELETE SEG FROM WS( WS_ID, HOUSE ) 
CALL GKSSUPDATE WS ( WS_ID, GKS$K_PERFORM FLAG ) 
Cc Pause. Type RETURN when you are finished 
Cc viewing the picture. 
READ (5, *) 
Cc Associate HOUSE in WISS with WS_ID. 
3] CALL GKSSASSOC_SEG_WITH_WS( WS_ID, HOUSE ) 
Cc Update the surface to initiate the change. 


CALL GKSSUPDATE _WS( WS_ID, GKSS$K_PERFORM_FLAG ) 


CALL GKSS$DEACTIVATE_WS( WS ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$DEACTIVATE_WS( WISS ) 
CALL GKS$CLOSE_WS( WISS )_ 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ This line of code opens a WISS workstation. From this point forward, 
anytime DEC GKS stores output in a segment on the VT241, it stores 
the same output in the same segment on the WISS workstation. 


@ After this line of code is executed, the segment HOUSE is deleted from 
the workstation ws_id. However, the WISS workstation still retains the 
segment house. 


© Ifyou want the workstation ws_id to store the segment house again, you 
have to associate the segment with the workstation. Afterwards, ws_id 
stores the segment house. 
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EVALUATE TRANSFORMATION MATRIX 


Operating States: GKOP, WSOP, WSAC, SGOP 


Description 


Syntax 


The function EVALUATE TRANSFORMATION MATRIX accepts scaling, ro- 
tation, and translation component values, and then writes a transformation 
matrix to the last argument of the function. You specify the transformation 
matrix as an argument to SET SEGMENT TRANSFORMATION to establish 
a segment transformation. 


See Section 8.4.4 for a detailed description of segment transformation and 
transformation matrixes. 


GKS$EVAL_XFORM_MATRIX (fixed_point_x, fixed_point_y, 
translation_vec_x, 
translation_vec_y, rotation, 
scale_x, scale_y, type_of_ 
coordinates, 
transformation_matrix) 


GEVTM (fx, fy, x_vector, y_vector, rotate, scale_x, scale_y, 
we_ndc, matrix) 


gevaltran (ppoint, pshift, angle, pscale, coord, result) 
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Arguments 
fixed_point_x 
fixed_point_y 
data type: real 
access: read-only 
mechanism: by reference 


These arguments are the coordinates of the fixed point, used as the only 
constant coordinate point during scaling and as the axis point during 
segment rotation. You can express this point as a world coordinate point 
or as an NDC point depending on the value you passed to the argument 
type_of_coordinates. | 


If you do not wish to scale or rotate the segment, you can pass the value 0 
for both arguments. 


translation_vec_x 
translation_vec_y 


data type: real 
access: read-only 
mechanism: by reference 


These arguments express the coordinate values to be added to all segment X 
and Y values in order to alter the position of the segment. You can express 
these values as world coordinate values or as NDC values depending on the 
value you passed to the argument type_of_coordinates. 


If you do not wish to translate the segment, you can pass the value 0 for 


both arguments. 

rotation 

data type: real 

access: read-only 
mechanism: by reference 


This argument is the measure of the angle of segment rotation around 
the fixed point axis, in radians. To calculate radians, use the formula 360 
degrees = 2*pi. 

If you do not wish to rotate the segment, you can pass the value 0 for this 
argument. 
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scale_x 

scale_y 

data type: real 

access: read-only 
mechanism: by reference 


These arguments are the real number values that are multiplied times all 
the segment’s X and Y coordinates except the fixed point, to determine the 
new X and Y positions of the scaled segment. 


If you do not wish to scale the segment, you can pass the value 1.0 for these 
arguments. 


type_of_coordinates 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the flag that determines whether GKS uses world 
coordinates or NDC coordinate values for the fixed point and shift vector 
arguments. This argument can be either of the following values or constants: 


Value Constant Description 

0 GKS$K_COORDINATES_WC The fixed point and shift vectors are 
world coordinate values. 

1 GKS$K_COORDINATES_NDC The fixed point and shift vectors are 
NDC values. 


Use caution when specifying GKS$K_COORDINATES_WC. DEC GKS uses 
the current normalization transformation to transform the fixed point from 
world coordinates to NDC values. The current normalization transformation 
might not be the same as the one used during primitive generation. If 

the current normalization transformation is different, the result may be 
unexpected. 


transformation_matrix 


data type: array (real) 
access: write-only 
mechanism: by reference 


This argument is the six-element transformation matrix that results from 
the evaluation of the scaling, rotation, and shifting component values. You 
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can use this value as an argument to SET SEGMENT TRANSFORMATION 
to establish a segment transformation. You declare this argument as a 


six-element, single-dimension array. 


Error Messages 


Error Completion 

Number Status Code 

-20 DECGKS$_ERROR_NEG_20 
8 GKS$_ERROR_8 


Program Example 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be in one of the states GKOP, 
WSOP, WSAC, or SGOP in routine 


seo 


Refer to Example 8-2 in this chapter for a program example using a call to 


EVALUATE TRANSFORMATION MATRIX. 


8-60 Segment Functions 


INSERT SEGMENT 


INSERT SEGMENT 


Operating States: WSAC, SGOP 


Description 


Syntax 


The function INSERT SEGMENT takes a segment stored in a workstation 
Independent segment storage (WISS) workstation, transforms it according 
to the segment’s current transformation, and transforms it again according 
to the transformation matrix specified in the call to INSERT SEGMENT 
(the effect of the two transformations are cumulative). Then, if the 
operating state is GKS$K_WSAC (at least one workstation active), INSERT 
SEGMENT copies the segment’s oe primitives onto the surface of all 
active workstations. 


If you call INSERT SEGMENT when another segment is open (DEC GKS 
operating state GKS$K_SGOP), DEC GKS inserts the specified segment’s 
output primitives into the open segment. 


Whether or not you have a segment open at the time of the call to INSERT 
SEGMENT, the active workstations do not store the inserted segment 
primitives as a segment; the workstations only generate the inserted 
segment’s primitives. 


DEC GKS applies only the current clipping rectangle to the inserted 
primitives, and if a segment is currently open, applies the segment 
attributes of the open segment (transformation, highlighting, visibility, and 
so forth) to the inserted primitives. The inserted primitive’s attributes (line 
type, text expansion factor, and so forth) remain unchanged. 


GKSS$INSERT_SEG (segment_name, insertion_xform_matrix) 
GINSG (segment_name, matrix) 
ginsertseg (segment_name, segtran) 
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Arguments 
segment_name 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the integer value that identifies a stored segment. 


insertion_xform_matrix 


data type: array (real) 
access: read-only 
mechanism: by reference 


This argument is the six-element insertion transformation matrix. Ifa 
transformation has been specified for the segment to be inserted, DEC GKS 
calculates the accumulated effect of the segment transformation and then 
the insertion transformation, in that order. You can formulate an insertion 
transformation using either EVALUATE TRANSFORMATION MATRIX or 
ACCUMULATE TRANSFORMATION MATRIX. 


Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
5 GKS$_ERROR_5 

27 GKS$_ERROR_27 
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Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be either in the state WSAC 


or in the state SGOP in routine | 
RK 


Workstation Independent Segment 
Storage is not open in routine **** 


Error 
Number 


120 


124 


125 


Program Example 


Completion 
Status Code 


GKS$_ERROR_120 


GKS$_ERROR_124 


GKS$_ERROR_125 


INSERT SEGMENT 


Message 


Specified segment name is invalid 
in routine **** 


Specified segment does not exist 
on Workstation Independent 
Segment Storage in routine **** 


Specified segment is open in 
routine **** 


Example 8-8 illustrates the use of the function INSERT SEGMENT. 
Following the program example, Figure 8-10 illustrates the program’s effect 
on a VT241 workstation. 


Example 8-8: Inserting a Segment’s Primitives into Another Segment 
Cc This program draws a house in the lower left corner of the 
Cc screen and then inserts that house into other segments. 


IMPLICIT NONE 
INCLUDE ‘SYS$LIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, LOWER_LEFT CORNER, HOUSE_1, HOUSE_2, 
* WISS, NUM POINTS, UPPER_LEFT CORNER, 

* UPPER RIGHT CORNER, LOWER_RIGHT CORNER 

REAL PX ( 9 ), PY ( 9 ), NULL, NO_CHANGE, 

* XFORM MATRIX( 6 ), UP, RIGHT 


DATA PX / .4, .1, .1, .4, 
DATA PY / .1, .1, .7, .7, 


25, il; 4, 4, 


a4 
sO pela: aedge eG ahi of, 


DATA NUM POINTS / 9 /, LOWER_LEFT_CORNER / 1 /, 
* HOUSE_1 / 1 /, HOUSE_2 / 2 /, WISS / 2 /, 
* NULL / 0.0 /, NO_CHANGE / 1.0 /, WS_ID/1 /, 


* UP / 0.5 /, RIGHT / 0.5 / 


CALL GKSSOPEN_GKS( ’SYS$ERROR:’ ) 

CALL GKS$OPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKSSOPEN_WS( WISS, GKS$K_CONID_ DEFAULT, 

* GKSS$K_WSTYPE WISS ) 


(continued on next page) 
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Example 8-8 (Cont.): Inserting a Segment’s Primitives into Another 
Segment 





CALL GKSSACTIVATE _WS( WS_ID ) 
CALL GKSS$ACTIVATE _WS( WISS ) 


0 CALL GKS$SET_VIEWPORT( LOWER_LEFT CORNER, 0.0, 0.5, 0.0, 0.5 ) 


Cc Create a segment in the lower left corner of the surface. 
CALL GKSS$CREATE_SEG( HOUSE_1 ) 
CALL GKS$SELECT_XFORM( LOWER_LEFT CORNER ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG () 


Cc Deactivate WISS so that no other segments are stored there. 
CALL GKS$DEACTIVATE_WS( WISS ) 


Cc Turn off the clipping so that transformed houses are visible. 
CALL GKS$SET_CLIPPING( GKS$K_NOCLIP ) 


Cc Change the matrix value. 
CALL GKS$EVAL_XFORM MATRIX( NULL, NULL, RIGHT, NULL, 
* NULL, NO_CHANGE, NO CHANGE, GKS$K_COORDINATES_NDC, 
* XFORM MATRIX ) 


Cc Create a segment in the lower right corner by inserting 
c HOUSE_1’s primitives into HOUSE _2. 
CALL GKS$CREATE_SEG( HOUSE_2 ) 
2) CALL GKS$INSERT_SEG( HOUSE_1, XFORM_MATRIX ) 


CALL GKS$CLOSE_SEG () 


Cc Change the matrix value. 
CALL GKSS$EVAL_XFORM_MATRIX( NULL, NULL, NULL, UP, 
* NULL, NO_CHANGE, NO_CHANGE, GKS$K_COORDINATES_NDC, 
* XFORM MATRIX ) 


Cc Just insert the primitives in the upper left corner using 
Cc GKS$INSERT_SEG. 

© CALL GKS$INSERT_SEG( HOUSE_1, XFORM MATRIX ) 
Cc Change the matrix value. 


CALL GKS$EVAL_XFORM_MATRIX( NULL, NULL, RIGHT, UP, 
* NULL, NO CHANGE, NO_CHANGE, GKS$K_COORDINATES_NDC, 
* XFORM MATRIX ) 


Cc Just insert the primitives in the upper right corner using 
Cc GKS$INSERT_SEG. 
CALL GKSSINSERT_SEG( HOUSE_1, XFORM_MATRIX ) 


(continued on next page) 
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Example 8-8 (Cont.): Inserting a Segment’s Primitives into Another 


Segment 
Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 
CALL GKS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 
READ (5, *) 
Cc Redraw all the segments. House primitives at the top are deleted. 


CALL GKS$REDRAW_SEG_ON_WS( WS_ID ) 


CALL GKS$DEACTIVATE WS( WS_ID ) 
CALL GKS$CLOSE_WS( WISS ) 

CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ These lines of code establish the normalization window to be the lower 
left corner of the NDC space. 


@ Using EVALUATE TRANSFORMATION MATRIX, you can create the 
transformation matrix that you need to pass to INSERT SEGMENT as 
an argument. This matrix specifies a position translation of 0.5 NDC 
points to the right. When this matrix is passed to INSERT SEGMENT 
while a segment is open, the house’s primitives are transformed and 
made a part of the open segment. 

© Inserting segments when the DEC GKS operating state is 
GKS$K_WSAC causes the output primitives to be written to the work- 
station surface, but the primitives are not stored in a segment. These 
segment primitives are translated 0.5 NDC points in an upwards direc- 
tion. 


@ The call to REDRAW ALL SEGMENTS ON WORKSTATION redraws all 
segments and deletes all primitives outside of segments. 
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Figure 8-10: Inserting a Segment’s Primitives into Another Segment— 
VT241 
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Figure 8—10 shows the screen of a VT241 terminal after the program has 
run to completion. 
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RENAME SEGMENT 


Operating States: WSOP, WSAC, SGOP. 


Description 


The function RENAME SEGMENT changes the segment name from its 
former name to a new name. Once you have renamed a segment, you can 
reuse the old segment name. 


Syntax 
GKS$RENAME_SEG (old_name, new_name) 
GRENSG /(old_name, new_name) 
grenameseg (old, new) 
Arguments 
old_name 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the integer value that was used to identify the segment. 
After the call to RENAME SEGMENT, you are free to use this identifier to 
name another segment. 


new_name 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the integer value that now identifies the segment. 
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Error Messages 


120 
121 


122 


Program Example 


Completion 
Status Code 


DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_120 
GKS$_ERROR_121 


GKS$_ERROR_122 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 
Specified segment name is invalid 
in routine **** 

Specified segment name is already 
in use in routine **** 


Specified segment does not exist in 
routine **** 


Example 8-9 illustrates the use of the function RENAME SEGMENT. 
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Example 8-9: Renaming a Segment 


aoe 


C 


This program draws a house in the lower left corner of the 
screen and then renames it. 

IMPLICIT NONE . 

INCLUDE ’SYSS$LIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, LOWER_LEFT CORNER, HOUSE_1, HOUSE _2, 

* LOWER_RIGHT_CORNER, UPPER_LEFT_CORNER, HOUSE_3, 

* NUM_POINTS 

REAL PX ( 9 ), PY (9 ) 

DATA PX / .4, .1, .1, .4, .25, .1, .4, .4, .1 / 

DATA PY / 2.1, slp oT, 3 7y 6 9p Tp sly Te 21 

DATA NUM_POINTS / 9 /, LOWER_LEFT_CORNER / 1 /, 

* HOUSE_1 / 1 /, HOUSE_2 / 2 /, LOWER_RIGHT_CORNER / 2 /, 
* UPPER_LEFT_CORNER / 3 /, HOUSE_3 / 3 /, WS_ID / 1 / 


CALL GKSSOPEN_GKS( 'SYS$ERROR:’ ) 
CALL GKSSOPEN WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKSS$ACTIVATE_WS( WS_ID ) 


CALL GKS$SET_VIEWPORT( LOWER_LEFT_ CORNER, 0.0, 0.5, 0.0, 0.5 ) 
CALL GKS$SET_VIEWPORT( LOWER_RIGHT CORNER, 0.5, 1.0, 0.0, 0.5 ) 
CALL GKS$SET_VIEWPORT( UPPER_LEFT_CORNER, 0.0, 0.5, 0.5, 1.0 ) 


Create a segment in the lower left corner of the surface. 
CALL GKS$CREATE_SEG( HOUSE_1 ) 

CALL GKS$SELECT_XFORM( LOWER_LEFT_ CORNER ) 

CALL GKSS$POLYLINE( NUM_POINTS, PX, PY ) 

CALL GKSS$CLOSE_SEG() 


Create a second segment in the lower right corner of the surface. 
CALL GKS$CREATE_SEG( HOUSE_2 ) 

CALL GKS$SELECT_XFORM( LOWER_RIGHT_CORNER ) 

CALL GKSS$POLYLINE( NUM_POINTS, PX, PY ) 

CALL GKS$CLOSE_SEG() 


Create a third segment in the upper left corner of the surface. 
CALL GKSS$CREATE_SEG( HOUSE_3 ) 

CALL GKS$SELECT_XFORM( UPPER_LEFT_CORNER ) 

CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 

CALL GKS$CLOSE_SEG() 


Delete houses 1 and 2. 
CALL GKSSDELETE_SEG( HOUSE_1 ) 
CALL GKS$DELETE_SEG( HOUSE_2 ) 
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Cc Redraw all the segments. 
CALL GKS$REDRAW_SEG_ON_WS( WS_ID ) 


Cc Since it is the only one left, rename HOUSE_3 to be HOUSE_1. 
2] CALL GKSSRENAME SEG( HOUSE_3, HOUSE_1 ) 


CALL GKSSDEACTIVATE WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ These lines of code establish three different normalization transforma- 
tions in three corners of the NDC plane. 


@ After deleting segments, you may want to keep all closed segments in 
numerical order. You can use RENAME SEGMENT to maintain an 
orderly progression of segment names. 


8-70 Segment Functions 


SET DETECTABILITY 


SET DETECTABILITY 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SET DETECTABILITY controls the segment attribute that 
determines whether or not the user can choose a segment during pick input. 
(A segment has to be both detectable and visible in order to be picked.) 


Syntax 
SET DETECTABILITY (segment_name, detectability_flag) 
GSDTEC (segment_name, detect) 
gsetdet (segment_name, detectability) 
Arguments 
segment_name 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the integer value that identifies a stored segment. 


detectability_flag 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the flag that determines whether or not the user can pick 
the specified segment. By default, DEC GKS segments are 
GKS$K_UNDETECTABLE. This argument can be either of the following 
values or constants. 
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Value Constant Description 
0 GKS$K_UNDETECTABLE You cannot pick the segment. 
1 GKS$K_DETECTABLE You can pick the segment, if visible. 


Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
7 GKS$_ERROR_7 

120 GKS$_ERROR_120 

122 GKS$_ERROR_122 


Program Example 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 


shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified segment name is invalid 
in routine **** 


Specified segment does not exist in 
routine **** 


Example 8-10 illustrates the use of the function SET DETECTABILITY. 
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Example 8-10: Controlling the Detectability of Segments 


Cc This program draws a house in the lower left corner of the 
Cc screen and an undetectable house in the upper right corner. 
IMPLICIT NONE 
INCLUDE ’SYS$LIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, LOWER_LEFT_ CORNER, HOUSE_1, HOUSE_2, 
* UPPER_RIGHT CORNER, INITIAL STATUS, 
* PICK_ID, PROMPT ECHO TYPE, ERROR_STATUS, SEGMENT NAME, 
* INPUT MODE, ECHO FLAG, RECORD BUFFER_LENGTH, RECORD SIZE, 
* INPUT STATUS, NUM_POINTS, DEVICE_NUM 
REAL PX ( 9 ), PY ( 9 ), BCHO_AREA( 4 ), DATA_RECORD( 1 ) 
DATA PX / .4, .1, .1, .4, .25, .1, .4, .4, .1/ 
DATA PY </ sty. -sBy Ty ST 29p Tp le Te a I 
DATA NUM_POINTS / 9 /, LOWER_LEFT CORNER / 1 /, 
* HOUSE_1 a as ae HOUSE _2 / 2 re UPPER | RIGHT_CORNER / 2 /, 
* WS ID / 1 /, DEVICE_NUM / 1 / 


CALL GKS$OPEN_GKS( ‘’SYSSERROR:’ ) 
CALL GKSSOPEN | | WS( WS_ID, GKS$K_CONID DEFAULT, GKSS$K_VT240 ) 
CALL GKS$ACTIVATE _WS( WS_ID ) 


CALL GKS$SET_VIEWPORT( LOWER_LEFT CORNER, 0.0, 0.5, 0.0, 0.5 ) 
CALL GKS$SET_VIEWPORT( UPPER_RIGHT CORNER, 0.5, 1.0, 0.5, 1.0 ) 


C Create a segment in the lower left corner of the surface. 
CALL GKS$CREATE_. SEG ( HOUSE_1 ) 
CALL GKSSSELECT . |_XFORM ( LOWER _ LEFT CORNER } 
CALL GKS$POLYLINE ( NUM | POINTS, PX, PY ) 
CALL GKS$CLOSE __SEG () 


Cc Create a second segment in the upper right corner of the surface. 
CALL GKS$CREATE_SEG( HOUSE_2 ) 
CALL GKSS$SELECT - '_XFORM ( UPPER _| RIGHT CORNER ) 
CALL GKS$POLYLINE( NUM | POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG () 


Cc Make HOUSE_1 detectable. 
CALL GKSS$SET_SEG DETECTABILITY ( HOUSE_1, GKS$K_DETECTABLE ) 





(continued on next page) 
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c Inquire, initialize, set, and request pick input. 

RECORD BUFFER_LENGTH = 4 

@ CALL GKS$INQ_PICK_STATE( WS_ID, DEVICE_NUM, 
* GKS$K_VALUE REALIZED, ERROR _STATUS, INPUT _MODE, 
* ECHO FLAG, INITIAL STATUS, SEGMENT NAME, PICK_ID, 
* PROMPT ECHO TYPE, ECHO_AREA, DATA_RECORD, 
* RECORD BUFFER_LENGTH, RECORD SIZE ) 

3] SEGMENT NAME = HOUSE_1 
PROMPT ECHO TYPE = 1 
DEVICE_NUM = 1 
ECHO_AREA( 1 ) = 0.0 
ECHO_AREA( 2 ) = 479.0 
ECHO AREA( 3 ) = 0.0 
ECHO AREA( 4 ) = 479.0 

4] CALL GKS$INIT_PICK( WS_ID, DEVICE_NUM, 


* GKS$K_STATUS OK, SEGMENT NAME, PICK_ID, 
* PROMPT ECHO TYPE, ECHO AREA, DATA_RECORD, 
* RECORD _BUFFER_LENGTH ) 


15 CALL GKS$SET_PICK_MODE( WS_ID, DEVICE_NUM, 
* GKS$K_INPUT_MODE_REQUEST, GKS$K_ECHO ) 


© CALL GKS$REQUEST_PICK( WS_ID, DEVICE_NUM, INPUT_STATUS, 
* SEGMENT NAME, PICK_ID ) 


Cc Output the input segment name. 
@ WRITE (6,*) INPUT_STATUS, SEGMENT NAME 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 
@ By setting the segment attribute of house_1 to GKS$K_DETECTABLE, 
you allow the segment to be picked during input. 


@ The function INQUIRE PICK DEVICE STATE obtains default values 
needed for pick input. For more information, refer to Chapter 11, Inquiry 
Functions. 
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Setting the segment name to house_1 ensures an initial pick value of 1. 
Since house_2 is undetectable, you cannot set the initial segment name 
to be 2. 


The call to INITIALIZE PICK initializes input values. For more infor- 
mation concerning this function, refer to Chapter 7, Input Functions. 


The call to SET PICK MODE controls the prompt echo. For more infor- 
mation concerning this function, refer to Chapter 7, Input Functions. 


The call to REQUEST PICK initiates pick input. 
No matter how many times you execute this program, you will never be 
able to pick house_2, so that the returned segment name has the value 2. 


The variable input_status determines whether or not the input is valid 
(refer to Chapter 7, Input Functions). 


If you attempt to pick house_2, this function always writes an input status 
value of GKS$K_STATUS_NOPICK and a segment_name value of 1 (the 
integer value associated with house_1). 


Figure 8-11 shows the screen of a VT241 terminal if the user attempts 

to pick the undetectable house. Notice that the graphics handler does not 
outline the house’s extent rectangle; this tells the user that the house is not 
detectable. 
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Figure 8-11: Setting Pick Detectability—VT241 
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SET HIGHLIGHTING 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SET HIGHLIGHTING controls the segment attribute that 
determines whether or not the specified segment is highlighted. 


For example, if you use this function to highlight a segment on a VT241, 
DEC GKS places the segment extent rectangle into an alternative fore- 
ground color to draw attention to the specified segment. 


If you attempt to highlight an invisible segment, the highlighting does not 
take effect until you make the segment visible again. 


Syntax 

GKS$SET_SEG_HIGHLIGHTING (segment_name, 

highlighting_flag) 

GSHLIT (segment_name, high) 

gsethighlight (segment_name, highlighting) 
Arguments 

segment_name 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the integer value that identifies a stored segment. 
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highlighting_flag 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the flag that determines whether or not DEC GKS 
highlights the specified segment. By default, DEC GKS segments are 
not highlighted. This argument can be either of the following values or 


constants: 

Value Constant Description 

0 GKS$K_NORMAL DEC GKS does not highlight the segment. 

1 GKS$K_HIGHLIGHTED DEC GKS highlights the segment, if visible. 


Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
1 GKS$_ERROR_7 

120 GKS$_ERROR_120 

122 GKS$_ERROR_122 


Program Example 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 


shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified segment name is invalid 
in routine **** 


Specified segment does not exist in 
routine **** 


Example 8-11 illustrates the use of the function SET HIGHLIGHTING. 
Following the program example, Figure 8-12 illustrates the program’s effect 


on a VT241 workstation. 
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Example 8-11: Highlighting a Segment 


C This program draws a house in the lower left corner of the 
Cc screen and a highlighted house in the upper right. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, LOWER_LEFT CORNER, HOUSE 1, HOUSE_2, 
* UPPER_RIGHT CORNER, NUM POINTS 
REAL PX (9 ), PY (9) 
DATA PX / .4, .1, .1, .4, .25, .1, .4, .4, .1 / 
DATA PY / .1, .1, .7, «7, .9, «7, «4, «7, «1 / 
DATA NUM POINTS / 9 /, LOWER _| LEFT CORNER /1f/, 
* HOUSE 1 of 1 /, HOUSE_2 / 2 qi UPPER . RIGHT_CORNER /2¢, 
* WS_ID i ae 


CALL GKSSOPEN_GKS( ‘’SYS$ERROR:’ ) 
CALL GKSSOPEN_WS( WS_ID, GKS$K_CONID_ DEFAULT, GKS$K_VT240 ) 
CALL GKSSACTIVATE WS( WS_ID ) 


CALL GKS$SET_VIEWPORT( LOWER_LEFT CORNER, 0.0, 0.5, 0.0, 0.5 ) 
CALL GKS$SET_VIEWPORT( UPPER_RIGHT_CORNER, 0.5, 1.0, 0.5, 1.0 ) 


Cc Create a segment in the lower left corner of the surface. 
CALL GKSSCREATE_SEG( HOUSE 1 ) 
CALL GKS$SELECT_XFORM ( LOWER _| LEFT CORNER ) 
CALL GKSSPOLYLINE ( NUM POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG() 


Cc Create a second segment in the upper right corner of the surface. 
CALL GKSS$CREATE_SEG( HOUSE_2 ) 
CALL GKSS$SELECT_XFORM ( UPPER | RIGHT CORNER ) 
CALL GKSSPOLYLINE ( NUM POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG() 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 
Cc Highlight HOUSE 2. 


CALL GKS$SET__ SEG ; HIGHLIGHTING( HOUSE_2, GKS$K_HIGHLIGHTED ) 


Cc Update the surface to initiate the change. 
CALL GKSSUPDATE _WS( WS_ID, GKS$K_PERFORM_FLAG ) 
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CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


Figure 8-12 shows the screen of a VT241 terminal after the first pause in 
the program. 


Figure 8-12: Highlighting a Segment—VT241 
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SET SEGMENT PRIORITY 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SET SEGMENT PRIORITY sets the segment attribute that 
determines which segment takes priority when two segments overlap on the 
workstation surface. The segment priority determines which segment takes 
precedence on the workstation surface, and which segment is chosen if the 
user chooses the overlapping area during pick input. 


DEC GKS implements segment priority on a scale of real numbers from the 
value 0.0 to the value 1.0. Segments with the priority 0.0 have the lowest 
priority, and segments with the priority 1.0 have the highest priority. 


Different devices implement segment priority differently. Either a device 
supports an infinite number of priorities (theoretically), or the device 
supports a specific number of priorities. If the device supports an infinite 
amount of priorities, the maximum number of segment priorities supported 
entry in the workstation description table is the value 0. Otherwise, the 
entry contains the number of priorities supported. (To access this table 
entry, call the function INQUIRE SEGMENT PRIORITY.) 


If the number of priorities supported is not 0.0, then DEC GKS divides the 
0.0 to 1.0 priority range into subranges according to the number of supported 
priorities. If you specify, for two different segments, two different priority 
values that fall within the same subrange, those segments have the same 
priority. For instance, if a workstation supports two segment priorities, all 
segments with the specified values between 0.0 and 0.5 inclusive have the 
same priority, and values between 0.51 and 1.0 have the same priority. 
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Syntax 
GKS$SET_SEG_PRIORITY (segment_name, priority) 
GSSGP_ (segment_name, priority) 
gsetsegpri (segment_name, priority) 
Arguments 
segment_name 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the integer value that identifies a stored segment. 


priority 

data type: real 

access: read-only 
mechanism: by reference 


This argument is a real number between the value 0 and the value 1.0 that 
determines the segment priority. The initial segment priority is the value 
0.0. For information concerning your device’s implementation of segment 
priority, refer to the DEC GKS Device Specifics Reference Manual. 
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Error 
Number 


—20 


120 
122 


126 


Program Example 


Completion 
Status Code 


DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_120 
GKS$_ERROR_122 


GKS$_ERROR_126 


SET SEGMENT PRIORITY 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 
Specified segment name is invalid 
in routine **** 

Specified segment does not exist in 
routine **** 

Segment priority is outside the 
range [0,1] in routine **** 


Example 8-12 illustrates the use of the function SET SEGMENT PRIORITY. 
Following the program example, Figure 8—13 illustrates the program’s effect 
on a VT241 workstation. 
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Example 8-12: Setting Segment Priorities 





This program draws a house in the lower left corner of the 
screen and a large house. Then, the program sets the smaller 
house to have a higher priority. 

IMPLICIT NONE 

INCLUDE ’ SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, LOWER_LEFT CORNER, SMALL HOUSE, 

* LARGE HOUSE, UNITY, NUM_POINTS, RED 

REAL PX ( 6 ), PY ( 6 ), HIGHER, LOWER 

DATA PX / .4, .1, .1, .25, .4, .4 / 

DATA PY / .1, .1, .7, .9, .7, .1 / 

DATA NUM POINTS / 6 /, LOWER_LEFT_ CORNER / 1 /, 

* SMALL_HOUSE / 1 /, LARGE nHOvEE /2/, UNITY / 0 /, 

* WS_ID / 1 /, HIGHER / 1.0 /, LOWER / 0.0 /, RED / 2 / 


aaa 


CALL GKS$OPEN_GKS( ‘SYSS$ERROR:’ ) 
CALL GKSS$OPEN WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


CALL GKS$SET_VIEWPORT( LOWER_LEFT CORNER, 0.0, 0.7, 0.0, 0.5 ) 


Cc Create a segment in the lower left corner of the surface. 
CALL GKS$CREATE_SEG( SMALL _HOUSE ) 
CALL GKSS$SELECT _XFORM ( LOWER _ LEFT_CORNER ) 


1] CALL GKS$SET_FILL_INT_STYLE( GKS$K_INTSTYLE_HOLLOW ) 
CALL GKS$FILL.. AREA ( NUM [| POINTS, PX, PY ) 
CALL GKS$CLOSE_. SEG () 


Cc Create a second segment in the upper right corner of the surface. 
CALL GKS$CREATE_SEG( LARGE HOUSE ) 
CALL GKS$SELECT_XFORM( UNITY ) 
Qe CALL GKS$SET_FILL_INT_STYLE( GKS$K_INTSTYLE_SOLID ) 
CALL GKS$SET_FILL_COLOR_INDEX( RED ) 
CALL GKSSFILL | AREA ( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_| SEG () 


Cc Release deferred output. Pause. Type RETURN when you are finished 


Cc viewing the picture. 
CALL GKSS$UPDATE_WS( WS_ID, GKS$K_POSTPONE_ FLAG ) 
READ (5, *) 
Cc Give the smaller house a higher priority. 
@ CALL GKS$SET_SEG_PRIORITY( LARGE_HOUSE, LOWER ) 


CALL GKS$SET_SEG_ PRIORITY ( SMALL HOUSE, HIGHER ) 





(continued on next page) 
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Example 8-12 (Cont.): Setting Segment Priorities 


Cc Redraw the segments. 
CALL GKS$REDRAW_SEG_ON_WS( WS_ID ) 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 


The following numbers correspond to the numbers in the previous example: 


@ These lines of code establish a hollow interior style for the small house. 


© These lines of code establish a solid interior style for the large house. 
The large house overlaps the smaller house. If you choose the overlapped 
area during pick input, the device would return the name of the larger 
house. | 


© By giving the smaller house a priority of 1.0 and the larger house a 
priority of 0.0, the smaller house has a higher priority. 


@ Once you redraw the segments, the new priorities take effect. The 
smaller house now overlaps the larger house. If you choose the over- 
lapped area during pick input, the device would now return the name of 
the smaller house. 


Figure 8-13 shows the screen of a VT241 terminal after the program has 
run to completion. 
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Figure 8-13: Setting Segment Priorities—VT241 
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SET SEGMENT TRANSFORMATION 


Operating States: WSOP, WSAC, SGOP 


Description 


Syntax 


The function SET SEGMENT TRANSFORMATION applies the translation, 
rotation, and scaling values of a segment transformation to the stored 
segment. You should use the functions EVALUATE TRANSFORMATION 
MATRIX and ACCUMULATE TRANSFORMATION MATRIX, described in 
this chapter, to create the transformation matrix. 


DEC GKS applies this segment transformation to all workstations that 

are currently storing the segment. Changes in segment transformation 
may or may not take place immediately. Depending on the capabilities of 
the workstation, you may have to update the surface in order to show the 
effects of a change in segment transformation (refer to the DEC GKS Device 
Specifics Reference Manual). 


Segment transformations are not cumulative. Every time you call SET 
SEGMENT TRANSFORMATION, DEC GKS applies the specified matrix to 
the segment as stored on NDC space. If you need to have a cumulative effect 
to segment transformations, refer to ACCUMULATE TRANSFORMATION 
MATRIX in this chapter. 


To understand the order in which DEC GKS applies different types of 
transformations, review the transformation and clipping pipeline in 
Figure 8—7. 


GKS$SET_SEG_ XFORM /(segment_name, 
transformation_matrix) 


GSSGT (segment_name, matrix) 
gsetsegtran (segment_name, segtran) 
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Arguments 
segment_name 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the integer value that identifies a stored segment. 


transformation_matrix 


data type: array (real) 
access: read-only 
mechanism: by reference 


This argument is a six-element transformation matrix created previ- 
ously by a call to either EVALUATE TRANSFORMATION MATRIX or 
ACCUMULATE TRANSFORMATION MATRIX. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

—22 DECGKS$_ERROR_NEG_22 Invalid segment transformation in 
routine **** 

7 GKS$_ERROR_7 GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 

120 GKS$_ERROR_120 Specified segment name is invalid 
in routine **** 

122 GKS$_ERROR_122 Specified segment does not exist in 


routine **** 
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Program Example 


Refer to Example 8—2 in this chapter for a program example using a call to 
SET SEGMENT TRANSFORMATION. 
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SET VISIBILITY 


Operating States: WSOP, WSAC, SGOP 


Description 


The function SET VISIBILITY sets the segment attribute that determines 
whether or not a segment is visible on the workstation surface. 


A segment must be both visible and detectable if you want the user to be 
able to choose the segment during pick input. 


Syntax 


GKS$SET_SEG VISIBILITY (segment_name, visibility_flag) 
GSVIS (segment_name, visible) 
gsetvis (segment_name, visibility) 


Arguments 


segment_name 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the integer value that identifies a stored segment. 


visibility_flag 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the flag that determines whether or not DEC GKS makes 
the specified segment visible on the workstation surface. By default, DEC 
GKS segments are GKS$K_VISIBLE. 
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SET VISIBILITY 


Depending on the capabilities of the device, and whether or not the specified 
segment overlaps other segments, you may need to call either UPDATE 
WORKSTATION or REDRAW ALL SEGMENTS ON WORKSTATION to 
update the picture on the surface of the workstation. For more information, 
refer to the DEC GKS Device Specifics Reference Manual. 


This argument can be either of the following values or constants: 


Value Constant Description 

0 GKS$K_INVISIBLE DEC GKS does not show the segment. 

1 GKS$K_VISIBLE DEC GKS shows the segment on the workstation 
surface. 


Error Messages 


Error Completion 

Number Status Code 

—20 DECGKS$_ERROR_NEG_20 
7 GKS$_ERROR_7 

120 GKS$_ERROR_120 

122 GKS$_ERROR_122 


Program Example 


Message 


GKS not in proper state: GKS in 
the error state in routine **** 


GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 
Specified segment name is invalid 
in routine **** 


Specified segment does not exist in 
routine **** 


Example 8-13 illustrates the use of the function SET VISIBILITY. 
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SET VISIBILITY 


Example 8-13: Setting the Visibility of a Segment 





C This program draws a house in the lower left corner of the 
C screen and an invisible house in the upper right corner. 
IMPLICIT NONE 
INCLUDE '’SYSS$LIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, LOWER_LEFT_CORNER, HOUSE_1, HOUSE _2, 
* UPPER_RIGHT_CORNER, NUM_POINTS 
REAL PX ( 9 ), PY (9 ) 
DATA PROS dy why aly 4p. w20p oy 3Sr wap ey 
DATA BY f- tadip: Shp ca Tae pe On, cele lee TK See 
DATA NUM_POINTS / 9 /, LOWER_LEFT CORNER / 1 /, 
* HOUSE_1 / 1 /, HOUSE_2 / 2 /, UPPER_RIGHT_CORNER / 2 /, 
* WS_ID / 1 / 


CALL GKSS$OPEN_GKS( 'SYS$ERROR:’ ) . 
CALL GKSSOPEN WS( WS_ID, GKS$K_CONID DEFAULT, GKS$K_VT240 ) 
CALL GKSS$ACTIVATE_WS( WS_ID ) 


CALL GKSS$SET_VIEWPORT( LOWER_LEFT CORNER, 0.0, 0.5, 0.0, 0.5 ) 
CALL GKS$SET_VIEWPORT( UPPER RIGHT CORNER, 0.5, 1.0, 0.5, 1.0 ) 


Cc Create a segment in the lower left corner of the surface. 
CALL GKSSCREATE_SEG( HOUSE_1 ) 
CALL GKSSSELECT_XFORM ( LOWER_LEFT CORNER ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG() 


Cc Create a second segment in the upper right corner of the surface. 
CALL GKS$CREATE_SEG( HOUSE_2 ) 
CALL GKSSSELECT_ XFORM( UPPER_RIGHT_CORNER ) 
CALL GKS$POLYLINE( NUM_POINTS, PX, PY ) 
CALL GKS$CLOSE_SEG() 


Cc Release deferred output. Pause. Type RETURN when you are finished 
Cc viewing the picture. 

CALL GKSSUPDATE_WS ( WS_ID, GKS$K_POSTPONE_FLAG ) 

READ (5, *) 
Cc Make HOUSE 2 invisible. 


CALL GKSS$SET_SEG VISIBILITY ( HOUSE_2, GKS$K_INVISIBLE ) 
CALL GKSSUPDATE_WS( WS_ID, GKS$K_PERFORM_FLAG ) 


Cc Pause. Type RETURN when you are finished 
Cc viewing the picture. 
READ (5, *) 


(continued on next page) 
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SET VISIBILITY 


Example 8-13 (Cont.): Setting the Visibility of a Segment 


Cc Make HOUSE_2 visible again. 
CALL GKS$SET_SEG_ VISIBILITY ( HOUSE_2, GKS$K_VISIBLE ) 


Cc Update the surface to initiate the change. 
CALL GKS$UPDATE_WS( WS_ID, GKS$K_PERFORM FLAG ) 


CALL GKS$DEACTIVATE_WS( WS_ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 

END 
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Chapter 9 


Metafile Functions 


The DEC GKS metafile functions provide a mechanism for long-term storage, 
communication, and reproduction of a graphical image. Metafiles created by 
an application can be used by other applications on other computer systems 
to reproduce a picture. When you store picture information in a metafile, 
you store specific information concerning the output primitives contained in 
the picture, the corresponding output attributes, and other information that 
may be needed to reproduce the picture. 


When DEC GKS creates a metafile, it uses one of two formats to store the 
information about the generated picture. DEC GKS can create either GKSM 
(GKS Metafiles) or CGM (Computer Graphics Metafiles) metafiles. 


The format of GKSM metafiles is defined by the GKS standard. When using 
the GKSM metafile format, DEC GKS stores an audit of the generation 

of DEC GKS primitives. All the programs in this chapter create and read 
GKSM metafiles. For more information concerning GKSM metafiles, refer to 
Section 9.1. 


The format of CGM metafiles is defined by the CGM ANSI X3.122-1986 
standard. This metafile format consists of a set of elements that can be 
used to describe a single graphical picture. CGM metafiles are designed 
for use with many types of graphics applications, including DEC GKS 
applications. If you need to create a CGM metafile for use with other 
applications, possibly on other systems, you can use DEC GKS to create the 
file. However, DEC GKS cannot read CGM metafiles. For more information 
concerning CGM metafiles, refer to Section 9.2. 


A short-term method of storing output primitives is to store them in 
segments. For more information concerning segments, refer to Chapter 8, 
Segment Functions. 
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9.1 Creating GKSM Metafiles 


9-2 


To create a GKSM metafile, you open and then activate a metafile work- 
station using the constant GKS$K_GKSM_OUTPUT (numeric value 2) as 
a workstation type for GKS$K_WSCAT_MO workstations. As the device 
connection, name the file specification of the file that is to contain the 
metafile information. (DEC GKS uses the file name exactly as specified, 
without using a default file extension.) You can open and activate as many 
GKS$K_GKSM_OUTPUT workstations as determined by the maximum 
allowable open and active workstations, sending appropriate output to the 
appropriate active GKS$K_GKSM_OUTPUT workstation. 


Once the GKS$K_GKSM_OUTPUT workstation is active, DEC GKS records 
information about the current state of the picture, such as output attribute 
information. Then, as you call DEC GKS functions, pertinent information 
about the function call is recorded in a metafile record. GKS$K_WSCAT_MO 
workstations record the following information: 


¢ The control functions that affect the appearance of the picture on the 
workstation surface. 


¢ Output primitives, if the GKS$K_WSCAT_MO workstation is active 
at the time of the function call. The primitives are stored in a form 
equivalent to NDC points. 


¢ Output attribute settings that are current at the time of primitive 
generation. 


¢ Segments, if the GKS$K_WSCAT_MO workstation is active at the time 
of the call to CREATE SEGMENT. 


¢ Geometric attribute data (such as character height, character-up vector, 
and so forth) affecting stored text primitives, in a form equivalent to 
normalized device coordinates (NDC). 


¢ Normalization transformation information such as the clipping rectangle. 
DEC GKS does not record workstation transformations. 


¢ Data that is specific to the application, or information that DEC GKS 
metafiles cannot store through standard calls to DEC GKS functions 
(stored using the function WRITE ITEM TO GKSM). 


If a call to a DEC GKS function is not applicable to the graphical picture, 
such as calls to certain control or inquiry functions, DEC GKS does not 
store the function call information in the metafile. Since metafiles record 
information pertinent to output only, DEC GKS metafiles do not record 
information about input function calls. 
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When you create a GKSM metafile, DEC GKS produces a metafile header, 
and for each function call necessary to reproduce the current environment, 
DEC GKS writes a series of items to the metafile. The items generated by a 
function call roughly correspond to the actual function call or to the state of 
the picture when the call was made. 


For each item, DEC GKS produces an item header and an item data record. 
The DEC GKS standard specifies this general format for data storage within 
GKSM metafiles (metafile header followed by an item header followed by an 
item data record, and so forth), but the individual item data record format 
is implementation specific. For instance, some implementations may store 
all item data as a string of characters, whereas some implementations 

may store some information as binary-encoded integer values and some 
information in character strings. 


An item type is an integer value that corresponds to a DEC GKS func- 
tion. For instance, an item of type 3 corresponds to a call to UPDATE 
WORKSTATION. The item type is contained in the item header. 


When creating GKSM metafiles, you do not need to be aware of the 
information contained in the item header or the item data record. Once you 
activate a GKS$K_GKSM_OUTPUT workstation and call output functions, 
DEC GKS formats the graphical output information within the metafile for 
you. 


When you close the GKS$K_WSCAT_MO workstation, DEC GKS writes 
an item of type 0 to the metafile to specify that it is the last item in the 
metafile. 


9.2 Creating CGM Metafiles 


To create a CGM metafile, you open and then activate a workstation using 
the constant GKS$K_CGM_OUTPUT (numeric value 7) as a workstation 
type for GKS$K_WSCAT_MO workstations. As the device connection, name 
the file specification of the file that is to contain the metafile information. 
(DEC GKS uses the file name exactly as specified, without using a default 
file extension.) You can open and activate as many GKS$K_CGM_OUTPUT 
workstations as determined by the maximum allowable open and active 
workstations, sending appropriate output to the appropriate active 
GKS$K_CGM_OUTPUT workstation. 
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Once the GKS$K_GKSM_OUTPUT workstation is active, DEC GKS places 
the graphical information into elements, by category. The element categories 
are as follows: 


Category Description 

Delimiter Elements Separate structures within the metafile. 

Metafile Descriptor Elements Describe the functional content and unique 
characteristics of the CGM metafile. 

Picture Descriptor Elements Define the limits of the virtual device coordi- 


nates (VDCs) and the parameter modes for 
the attribute elements. 


Control Elements Specify size and precision of VDC coordinates, 
and format descriptions of the CGM elements. 

Graphical Primitive Elements Describe the geometric objects in the picture. 

Attribute Elements Describe the various appearances of the 
graphical elements. 

Escape Elements Describe device- and system-specific function- 
ality. 

_ External Elements Pass information not needed for the creation 


of a picture (for instance, a message sent to 
the user of the metafile). 


The elements may have associated data. For instance, the graphical 
primitive elements may specify VDC points. (The DEC GKS NDC points 
correspond to the CGM VDC points.) DEC GKS determines the element 
data from your DEC GKS function calls. 


All the CGM metafile elements are grouped into structures that are similar 
in appearance to an application program. DEC GKS creates a metafile 
description at the top of the file. Other structures include the metafile 
default structure and the metafile picture structure. Each structure begins 
and ends with the appropriate delimiter elements. 


Unlike GKSM metafile items, CGM metafile elements have a certain format, 
or encoding. DEC GKS can create CGM metafile elements in one of the 
following encodings. 
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Encoding Description 


Character This encoding requires that the CGM metafile elements and their 
parameters be stored in a character-coded format as specified by the 
CGM standard. Using this encoding, your metafiles use a minimum 
amount of physical storage. 

Binary This encoding requires that the CGM metafile elements and their _ 
parameters be stored in binary code. Using this encoding, many of 
the applications and machines can store and read CGM metafiles 
with greater ease. 

Version 4.0 of DEC GKS does not support binary encoding. 

Clear Text This encoding requires that the CGM metafile elements and their 
parameters be stored in text. Using this encoding, you can type, 
print, or edit the CGM metafile so that you can review its contents 
before reading the file. 


To specify an encoding for your metafiles, you can use either of the following 
bit masks on the command line: 

%x00020007 Character encoding 

%x00040007 Clear text encoding 


If you choose, you can use bitmask constant values within your program to 
specify an encoding, as follows: 


CALL GKSS$OPEN_WS( WS_ID, ’CGM METAFILE.TXT’, 
* GKS$K_CGM_ OUTPUT .OR. GKS$M_CHARACTER_ ENCODING ) 


Cc or, 


CALL GKS$OPEN_WS( WS_ID, ‘CGM _METAFILE.TXT’, 
* GKSS$K_CGM_OUTPUT .OR. GKS$M_CLEAR_TEXT_ENCODING ) 


For more information concerning constants, refer to Appendix B, DEC GKS 
Constants. For more information concerning bitmasks, refer to Appendix A, 
DEC GKS Supported Workstations. 


Remember that when you create CGM metafiles, you do not need to be 
aware of the information contained in the individual elements. Once you 
activate a GKS$K_CGM_OUTPUT workstation and call output functions, 
DEC GKS formats the graphical output information within the metafile for 
you. 
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For detailed information concerning the CGM metafile format for the 
supported encodings, refer to Appendix E, DEC GKS Metafile Structures. 


NOTE 


DEC GKS Version 4.0 allows you to create CGM metafiles for 
other applications that may require this metafile format. This 
version of DEC GKS cannot read CGM metafiles. 


9.3 Reading a GKSM Metafile 


To reproduce a graphical image from a GKSM metafile, you must open a 
metafile input (GKS$K_WSCAT_MI) workstation. DEC GKS defines the 
constant GKS$K_GKSM_INPUT (numeric value 3) as the workstation type 
for GKS$K_WSCAT_MI workstations. Also, when you open the 
GKS$K_GKSM_INPUT workstation, specify the name of the file containing 
the recorded data items as the connection identifier argument. (DEC 

GKS uses the file name exactly as specified, without using a default file 
extension.) You can only open one GKS$K_GKSM_INPUT workstation for 
every corresponding physical file. 


When you open a GKS$K_GKSM_INPUT workstation, the first item that 
was written to the metafile becomes the current item. The current item is 
the item that is processed when you call the function GET ITEM TYPE 
FROM GKSM. As with GKS$K_GKSM_INPUT workstations, you can open 
as many GKS$K_GKSM_INPUT workstations as DEC GKS permits in 
total workstations, interpreting items from the appropriate metafile on the 
appropriate active workstations. 


To reproduce the graphic image stored in the metafile, you must call GET 
ITEM TYPE FROM GKSM, READ ITEM FROM GKSM, and INTERPRET 
ITEM for all the applicable items in the metafile, until you reach the item 
of type 0 (specifying the last item). The function GET ITEM TYPE FROM 
GKSM writes the item type, and the length of the data record of the current 
item, to its last two arguments. The function READ ITEM FROM GKSM 
writes the item data record to its last argument and causes the next item 
in the metafile to become the current item. The function INTERPRET 
ITEM reads information about an item and reproduces the desired action 
on all active GKS$K_WSCAT_OUTPUT and GKS$K_WSCAT_OUTIN 
workstations. 


In most applications, you call INTERPRET ITEM for all items in a metafile. 
However, there are instances when you may not wish to do this. 
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For example, if the creator of the metafile called the function WRITE ITEM 
TO GKSM to pass user-defined data to the metafile, then you need to handle 
this information in a special manner. For instance, if the user-defined data 
is a text string containing information for the application programmer, 
then, instead of passing the record to INTERPRET ITEM, you should store 
or write the text string as desired. You can identify user-defined data by 
checking the item type; all item types greater than 100 are items containing 
user-defined data. DEC GKS metafiles reserve item data numbers 1 through 
100. (If you are not using DEC GKS GKSM metafiles, the reserved item 
numbers may differ.) 


As another example, if you checked the item type and found it to be 3 (which 
is a call to the function UPDATE WORKSTATION), you may not want to 
interpret that item if it would delete important output primitives already on 
the workstation surface. For more information concerning the effects of a 
call to UPDATE WORKSTATION, refer to Chapter 3, Control Functions. 


If after calling GET ITEM TYPE FROM GKSM, you decide that you do not 
want to interpret the item, pass the value 0 as the data length argument to 
READ ITEM FROM GKSM. This skips the current item, causing the next 
item in the file to become the current item. 


9.4 Using the Metafile Functions in Programs 


Example 9-1 illustrates the creation of a GKSM metafile. 
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Example 9-1: Creating a Metafile 


This program creates a metafile that sends information about the 
programmer who created the metafile, and then draws a filled 
square in the middle of the NDC space. 

IMPLICIT NONE 

INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 

INTEGER WS_ID, META_OUT, USER_DEFINED, ITEM LENGTH, 
* NUM POINTS 

CHARACTER*80 CONTACT_INFO 

REAL PX ( 5 ), PY (5 ) 

DATA PX / .3, .7, .7, .3, .3 / 

DATA PY / .3, .3, .7, .7, .3 / 

DATA NUM_POINTS / 5 /, WS_ID / 1 /, META_OUT / 2 /, 

* USER_DEFINED / 101 /, ITEM_LENGTH / 80 / 


0 DATA CONTACT INFO 
* / "Programmers: Jim and Cathy D’’Augustine. 
* Telephone: 555-5555’ / 


qaqa 


CALL GKS$OPEN_GKS( ’SYSSERROR:’ ) 
CALL GKSS$OPEN WS( WS_ID, GKS$K_CONID_DEFAULT, GKS$K_VT240 ) 
CALL GKS$ACTIVATE_WS( WS_ID ) 


Cc Open and activate the MO workstation, sending data items to the 
Cc file METAFILE.DAT. 

CALL GKSSOPEN_WS( META OUT, ‘'METAFILE.DAT’, 

* GKS$K_GKSM_OUTPUT ) 


2] CALL GKS$ACTIVATE_WS( META_OUT ) 


Tell the next user of the metafile whom to call if 
problems are encountered. 


3) CALL GKSS$WRITE_ITEM( META OUT, USER_DEFINED, 
* ITEM LENGTH, SREF( CONTACT INFO ) ) 


C Set the interior fill style to solid. 
CALL GKS$SET_FILL_INT_STYLE( GKSS$K_INTSTYLE SOLID ) 


24 Draw the square in the middle of the NDC space. 
CALL GKS$FILL_AREA( NUM_POINTS, PX, PY ) 


Cc Close and deactivate all workstations 
CALL GKSS$DEACTIVATE_WS ( META OUT ) 
CALL GKSSCLOSE_WS ( META OUT ) 
CALL GKSSDEACTIVATE WS( WS_ID ) 
CALL GKS$CLOSE_WS ( WS_ID ) 
CALL GKS$CLOSE_GKS () 
END 





The following numbers correspond to the numbers in the previous example: 


@ This code initializes user-defined data to be sent to the metafile. This 
information includes the name of the programmer who created the 
metafile and the programmer’s telephone number. 
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@ Once you activate a GKS$K_WSCAT_MO workstation, DEC GKS writes 
all subsequent output, associated attributes, and current transformation 
information to the corresponding metafile. 


© The call to WRITE ITEM TO GKSM writes the user-defined data (in this 
example, information about the programmer who created the metafile) 
as an item in the metafile. The item type is user_defined or the value 
101. Any other programs using the created metafile must know that 
items numbered 101 pass this type of information, or the application can 
skip all user-defined information when using the metafile. 


For more information, refer to WRITE ITEM TO GKSM in this chapter. 


This program generates a square, solid, green fill area in the center of the 
workstation surface. 


Example 9—2 reads and interprets the metafile created by Example 9-1. 


Example 9-2: Interpreting and Producing a Picture from a Metafile 


Cc This program interprets and produces a picture from a 
Cc metafile. 
IMPLICIT NONE 
INCLUDE ’SYSSLIBRARY:GKSDEFS.FOR’ 
INTEGER WS_ID, META_IN, USER_DEFINED, ITEM LENGTH, 
* ITEM TYPE, MAX _LENGTH, END_METAFILE, CHAR LENGTH 
REAL ITEM DATA _RECORD( 500 ) net 
CHARACTER*80 CONTACT _INFO 
DATA WS_ID / 1 /, META_IN / 2 /, 
* USER_DEFINED / 100 /, MAX LENGTH / 500 /, 
* END _METAFILE / 0 /, CHAR_LENGTH / 80 / 


CALL GKSS$OPEN_GKS( ’SYSS$ERROR:’ ) 
CALL GKS$OPEN_WS( WS_ID, GKS$K_CONID_DEFAULT, GKSS$K_VT240 ) 
CALL GKSSACTIVATE_WS( WS_ID ) 


Cc Open the MI workstation. 


. CALL GKSSOPEN_WS( META_IN, ‘METAFILE.DAT’, 
* GKS$K_GKSM_INPUT ) 


CALL GKSSGET_ITEM( META_IN, ITEM TYPE, ITEM_LENGTH ) 
DO WHILE( ITEM_TYPE .NE. END_METAFILE ) 


Cc If it is the contact programmer information... 
IF ( ITEM TYPE .GE. USER_DEFINED ) THEN 

CALL . GKSSREAD _ ITEM ( “META _ IN, CHAR _LENGTH, 

7 SREF ( CONTACT INFO ) ) 





(continued on next page) 
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Example 9-2 (Cont.): Interpreting and Producing a Picture from a 
Metafile 


Cc Open a file, store the contact information, and close the file. 
OPEN( UNIT=1, FILE=’TEMP.TXT’, STATUS=’NEW’ ) 
WRITE (1,*) CONTACT INFO 
CLOSE( UNIT=1 ) 


Cc Otherwise, read and interpret the item... 
ELSE 
CALL GKS$READ_ITEM ( META_IN, MAX LENGTH, 
ba ITEM DATA RECORD ) 
CALL GKSS$INTERPRET_ ITEM( ITEM_TYPE, ITEM_LENGTH, 
* ITEM _DATA_RECORD ) 
ENDIF 
Cc If you want to find out the item types actually written to the 
Cc metafile, you can include this line. 
Oc WRITE (6,*) ITEM _TYPE, ITEM_LENGTH 


Get another item. 
CALL GKSS$GET_ITEM ( META_IN, ITEM TYPE, ITEM LENGTH ) 
ENDDO 


Cc Close and deactivate all workstations 
CALL GKSS$CLOSE_WS ( META_IN ) 
CALL GKSSDEACTIVATE WS ( WS_ID ) 
CALL GKSS$CLOSE_WS( WS_ID ) 
CALL GKS$CLOSE_GKS () 
END 


The following numbers correspond to the numbers in the previous example: 


@ When you open a GKS$K_WSCAT_MI workstation, you can call 
GET ITEM TYPE FROM GKSM, READ ITEM FROM GKSM, and 
INTERPRET ITEM. These functions access items stored in the file 
METAFILE.DAT that was created by the program in Example 9-1. 


@ These lines of code estabish a loop to read all items in the metafile until 
the program reaches the last item (item of type 0). The example gets a 
single item and checks to see if it is item 0, which signifies the end of 
the metafile. If the item is not item 0, then the program enters the loop. 
The first call to the function GET ITEM TYPE FROM GKSM is outside 
of the loop. GET ITEM TYPE FROM GKSM writes the current item’s 


type and size to its last two arguments. The remaining calls to this 
function occur at the bottom of the loop. 
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© Ifthe item type is greater than the value 100, then the application must 
handle this user-defined information. This application must know that 
user-defined data with an item type of 101 contains a character string 
(specified in Example 9-1). 


Once you obtain the string, you can store it in a file, as this program 
does. 


@ Ifthe item does not contain user-defined data, then interpret the item 
and send all graphical information to all active workstations. 


© If you want to see the item types of every item read from this metafile, 
you can include this line of code. In this example, the item types are 
the values 71, 61, 1, 101, 43, and so forth. A value of 71 corresponds 
to the effects of a call to SET WORKSTATION WINDOW; a value of 
61 corresponds to the effects of a call to SELECT NORMALIZATION 
TRANSFORMATION; a value of 1 corresponds to the effects of a call to 
OPEN WORKSTATION; a value of 101 corresponds to user-defined data, 
which cannot be interpreted and must be handled according to its data 
type; a value of 43 corresponds to the effects of a call to SET ASPECT 
SOURCE FLAGS, and so forth. For a complete list of item types and 
their corresponding DEC GKS function calls, refer to Appendix E, DEC 
GKS Metafile Structures. 


If you type the file containing the user-defined data from the metafile, you 
will see the following: 

$ TYPE TEMP.TXT [RETURN] 

Programmers: Jim and Cathy D’Augustine. Telephone: 555-5555 

For detailed information concerning the DEC GKS item types and other 
metafile structural information, refer to Appendix E, DEC GKS Metafile 
Structures. 


9.5 Metafile Inquiries 


The following list presents the inquiry functions that you can use to obtain 
information when writing device-independent code: 


INQUIRE LEVEL OF GKS 

INQUIRE LIST OF AVAILABLE WORKSTATION TYPES 
INQUIRE OPERATING STATE VALUE 

INQUIRE SET OF OPEN WORKSTATIONS 

INQUIRE WORKSTATION STATE 


For more information concerning device-independent programming, refer to 
the DEC GKS User Manual. 
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9.6 Function Descriptions 


This section describes the DEC GKS metafile functions in detail. All of the 
DEC GKS metafile functions work with GKSM metafiles only. 
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GET ITEM TYPE FROM GKSM 


GET ITEM TYPE FROM GKSM 


Operating States: WSOP, WSAC, SGOP 


Description 


The function GET ITEM TYPE FROM GKSM writes the item type and the 
length of the item data record, from the current item in a metafile, to the 
last two arguments. 


Format 
GKS$GET_ITEM (workstation_id, item_type, item_data_length) 
GGTITM (workstation_id, item_type, len_dr) 
ggettypegksm (workstation_id, result) 
Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the integer value that represents an open metafile 

input (GKS$K_WSCAT_MI) workstation. You can open more than one 
GKS$K_WSCAT_MI workstation at a time, depending on the needs of your 
application. 


item_type 

data type: integer 
access: write-only 
mechanism: by reference 


This argument is an integer value that represents the DEC GKS function 
call corresponding to the metafile item type. 
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GET ITEM TYPE FROM GKSM 


For a list of item types and the corresponding function names, refer to 
Appendix E, DEC GKS Metafile Structures. 


item_data_length 


data type: integer 
access: write-only 
mechanism: by reference 


This argument is the length of the item data record, in bytes. You should 
compare this value with your maximum data size to make sure that you 
defined a data record variable large enough to hold the entire data record. 


Error Messages 


Error Completion 

Number Status Code Message 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 

20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 

25 GKS$_ERROR_25 Specified workstation is not open 
in routine **** 

34 GKS$_ERROR_34 Specified workstation is not of 
category MI in routine **** 

162 GKS$_ERROR_162 No item is left in GKS Metafile 
input in routine **** 

163 GKS$_ERROR_163 Metafile item is invalid in routine 


REE 
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GET ITEM TYPE FROM GKSM 


Program Example 


For an example of a call to this function, see Example 9-2. 
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INTERPRET ITEM 


Operating States: WSOP, WSAC, SGOP 


Description 


The function INTERPRET ITEM reads an item data record obtained by 
a call to READ ITEM FROM GKSM. Then, if the item type corresponds 
to a call to a function that affects graphical representation, this function 
makes appropriate changes to the DEC GKS state list, and generates the 
specified graphical output on all active GKS$K_WSCAT_OUTPUT and 
GKS$K_WSCAT_OUTIN workstations. 


If the item type identifies user-defined data, INTERPRET ITEM generates 
an error indicating that it cannot interpret the item. 


Format 
GKSSINTERPRET_ITEM (item_iype, item_data_length, 
item_data_record) 
GIITM = (item_type, len_dr, dim_dr, dr) 
ginterpret (typeandlength, date) 
Arguments 
item_type 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that represents the DEC GKS function 
call corresponding to the metafile item type. You can obtain this value by 
calling the function GET ITEM TYPE FROM GKSM. For a list of item 
types and the corresponding function names, refer to Appendix E, DEC GKS 
Metafile Structures. 
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item_data_length 


data type: _ integer 
access: read-only 
mechanism: by reference 


This argument is the length of the item data record, in bytes. You can 
obtain this value by calling the function GET ITEM TYPE FROM GKSM. 


item_data_record 


data type: record 
access: read-only 
mechanism: by reference 


This argument is the item’s data record. You can obtain the item’s data 
record by calling the function READ ITEM TYPE FROM GKSM. 


Error Messages 


Error Completion 

Number Status Code Message 

-18 DECGKS$_ERROR_NEG_18 The following error occurred when 
GKS was interpreting an item 
RK 

—20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

7 GKS$_ERROR_7 GKS not in proper state: GKS 
shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 

161 GKS$_ERROR_161 Item length is invalid in routine 
RoR 

163 GKS$_ERROR_163 Metafile item is invalid in routine 


RK 
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Error Completion 

Number Status Code Message 

164 GKS$_ERROR_164 _ Item type is not a valid GKS item 

in routine **** 

165 GKS$_ERROR_165 Content of item data record is 
invalid for the specified item type 
in routine **** 

167 GKS$_ERROR_167 User item cannot be interpreted in 
routine **** 

168 GKS$_ERROR_168 Specified function is not supported 


in this level of GKS in routine 
KEKE 


Program Example 


For an example of a call to this function, see Example 9-2. 


9-18 Metafile Functions 


READ ITEM FROM GKSM 


READ ITEM FROM GKSM 


Operating States: WSOP, WSAC, SGOP 


Description 


Format 


The function READ ITEM FROM GKSM reads the current metafile item’s 
data record and then writes the record to its last argument. 


You should compare the maximum length for the data record (as passed to 
this function) with the actual length of the data record (as GET ITEM TYPE 
FROM GKSM writes to one of its arguments). If the actual size of the record 
is larger than the maximum allocated spate DEC GKS truncates the record 
causing loss of information. 


After returning the item’s data record to the application program, READ 
ITEM FROM GKSM makes the next item in the metafile the current item. 
If you want to skip an item for any reason, specify the value 0 as the 
maximum record length; this causes the next item in the metafile to become 
the current item. 


GKS$READ_ITEM (workstation_id, max_record_length, 
item_data_record) 


GRDITM = (workstation_id, len_dr, len_buf, dr_buf) 
greadgksm_  (workstation_id, length, record) 
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READ ITEM FROM GKSM 


Arguments 


9-20 


workstation_id 

data type: integer 
access: read-only 
mechanism: by reference 


This argument is the integer value that represents an open metafile 

input (GKS$K_WSCAT_MI) workstation. You can open more than one 
GKS$K_WSCAT_MI workstation at a time, depending on the needs of your 
application. 


maximum_record_size 


data type: integer 
access: read-only 
mechanism: by reference 


This argument is the maximum length of the declared variable that is to 
hold the item’s data record, in bytes. If the actual data record is larger than 
this maximum value, DEC GKS truncates the item’s data record. 


item_data_record 


data type: record 
access: write-only 
mechanism: by reference 


This argument is the item’s data record. 
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Error Messages 


Error 
Number 


—20 


20 
25 
34 
162 
163 


165 


166 


Program Example 


Completion 
Status Code 
DECGKS$_ERROR_NEG_20 


GKS$_ERROR_7 


GKS$_ERROR_20 
GKS$_ERROR_25 
GKS$_ERROR_34 
GKS$_ERROR_162 
GKS$_ERROR_163 


GKS$_ERROR_165 


GKS$_ERROR_166 


READ ITEM FROM GKSM 


Message 


_ GKS not in proper state: GKS in 


the error state in routine **** 
GKS not in proper state: GKS 


shall be in one of the states WSOP, 
WSAC, or SGOP in routine **** 


Specified workstation identifier is 
invalid in routine **** 


Specified workstation is not open 
in routine **** 


Specified workstation is not of 
category MI in routine **** 

No item is left in GKS Metafile 
input in routine **** 

Metafile item is invalid in routine 
ek . 


Content of item data record is 
invalid for the specified item type 
in routine **** 


Maximum item data record is 
invalid in routine **** 


For an example of a call to this function, see Example 9-2. 
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WRITE ITEM TO GKSM 


Operating States: WSAC, SGOP 


Description 


Format 


The function WRITE ITEM TO GKSM writes a user-defined data item 
record to a metafile. 


For example, you could precede each call to an output function by writing 
a character string to the metafile, describing the component of the picture 
generated by the subsequent function call. You can establish a specific 
item type greater than the value 100 to specify such a description. As an 
alternative, the application program can treat any item type greater than 
the value 100 as such a description. 


If you are using a metafile structure that is different from a GKSM 
metafile, you may have to specify different item data record values to this 
function. For more information concerning the structure of DEC GKS GKSM 
metafiles, refer to Appendix E, DEC GKS Metafile Structures. 


GKSS$WRITE_ITEM (workstation_id, item_type, item_data_length, 
item_data_record) 


GWITM = (workstation_id, item_type, len_dr, dim_dr, dr) 
gwritegksm (workstation_id, type, length, data) 
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Arguments 
workstation_id 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the integer value that represents an active metafile 
output (GKS$K_WSCAT_MO) workstation. You can activate more than one 
GKS$K_WSCAT_MO metafile at one time, depending on the needs of your 


application. 

item_type 

data type: integer 
access: read-only 
mechanism: by reference 


This argument is an integer value that represents the DEC GKS function 
call corresponding to the metafile item type. You can only use item types 
greater than the value 100 for user-defined data. 


item_data_length 


data type: integer 
access: read-only 
mechanism:. by reference 


This argument is the length of the item data record, in bytes. 


item_data_record 


data type: record 
access: read-only 
mechanism: by reference 


This argument is the item’s data record. 


Metafile Functions 9-23 


WRITE ITEM TO GKSM 


Error Messages 


Error Completion 

Number Status Code Message 

~20 DECGKS$_ERROR_NEG_20 GKS not in proper state: GKS in 
the error state in routine **** 

5 GKS$_ERROR_5 GKS not in proper state: GKS 
shall be either in the state WSAC 
or in the state SGOP in routine 
eK 

20 GKS$_ERROR_20 Specified workstation identifier is 
invalid in routine **** 

30 GKS$_ERROR_30 Specified workstation is not active 
in routine **** 

32 GKS$_ERROR_32 Specified workstation is not of 
category MO in routine **** 

160 GKS$_ERROR_160 Item type is not allowed for user 
items in routine **** 

161 GKS$_ERROR_161 Item length is invalid in routine 


KKK 


Program Example 


For an example of a call to this function, see Example 9-1. | 
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Chapter 10 


Error-Handling Functions 





The DEC GKS error-handling functions provide a method for you to control 
the generation of messages to the user, and a method of exit when a DEC 
GKS function call generates an error. The following list presents the DEC 
GKS error-handling:functions: 


¢ EMERGENCY CLOSE GKS 
¢ ERROR HANDLING 

¢ ERROR LOGGING 

e SET ERROR HANDLER 


DEC GKS recognizes a number of error situations or conditions. These error 
conditions are detected within DEC GKS functions, within procedures called 
by DEC GKS functions (such as calls to the graphics handler procedures), or 
within other areas of the application program. 


For errors occurring in areas of the application program other than in 

DEC GKS function calls, either the application program regains control 

or program execution terminates abnormally. If the application program 
regains control, it can attempt to properly close DEC GKS or, failing that, 
attempt an emergency closure by calling the function EMERGENCY CLOSE 
GKS. If the program terminates abnormally, the results are unpredictable. 
In the worst case, you lose all graphical information produced before the 
error. 


For errors detected within procedures called by DEC GKS, if the procedure 
does not generate a fatal error, then the DEC GKS error handlers may 

be able to process the error. If the procedure does not generate a fatal 
error, you should be able to save graphical data. Otherwise, the application 
program regains control, or the application program is forced to call 
EMERGENCY CLOSE GKS, or in the worst case, you lose all graphical data 
produced before the error. 
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For errors detected within DEC GKS functions, DEC GKS performs the 
following tasks: 


1. Sets the DEC GKS error state to ON to prohibit modification of DEC 
GKS variables. 


2. Calls ERROR HANDLING and passes the appropriate arguments. 
3. Performs function-specific error reaction or cleanup. 
4. Sets the DEC GKS error state to OFF. 


You can allow DEC GKS to call its own error handler, or you can provide 
an error handler of your own. An application-supplied, error-handling 
function can interpret information about the error and store data in a data 
area for subsequent analysis. Since application-supplied handlers do not 
have to generate the standard DEC GKS error messages, such a handler 
can change the format or the text of the messages sent to the user. Also, 
application-supplied handlers can decide whether to abort a program or to 
continue despite generated errors, if the errors are not fatal. 


A fatal error occurs within DEC GKS when internal data structures 
are corrupted, or when accurate and meaningful execution of DEC GKS 
functions is no longer possible. When a fatal error occurs, DEC GKS 
executes the current error handler and then terminates execution of the 
application. 


The DEC GKS error-handling function calls the error-logging function to 
display an error message, and then control returns to the error-handling 
function. The DEC GKS error-handling function ERROR HANDLING 
is available to you as well. You can call ERROR HANDLING from an 
application-supplied handler, if you desire. 


The GKS standard dictates that every error-handling function, whether it be 
the DEC GKS supplied function or an application-supplied function, accept 
the following information from DEC GKS upon error generation: 


e The GKS error number corresponding to the appropriate error condition 
(refer to Appendix D, DEC GKS Error Messages) 
e The name of the GKS function that generated the error condition 


¢ The name of the error file specified in the application program in the call 
to OPEN GKS 


To implement an application-supplied, error-handling function, you must 
define a function with three parameters corresponding to the values listed 
previously: the DEC GKS error number, the name of the DEC GKS function 
that generated the error, and the name of the error file. 
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Then, you must pass the address of your error-handling function to SET 
ERROR HANDLER. For more information, refer to SET ERROR HANDLER 
in this chapter. 


10.1 Function Descriptions 


This section describes the DEC GKS error-handling functions in detail. 
Remember that none of the DEC GKS error-handling functions generate 
errors. 


Error-Handling Functions 10-3 


EMERGENCY CLOSE GKS 


EMERGENCY CLOSE GKS 


Operating States: GKCL, GKOP, WSOP, WSAC, SGOP 


Description 


The function EMERGENCY CLOSE GKS attempts to perform a rapid and 
orderly closure of DEC GKS. 


Usually, you call this function for error conditions detected outside of DEC 
GKS. If possible, the call to this function closes any open segment, updates 
all active workstations, deactivates those workstations, closes all open 
workstations, and then closes DEC GKS. 


Syntax 


GKS$EMERGENCY_CLOSE /() 
GECLKS /() 
gemergencyclosegks () 


Program Example 


Example 10-1 illustrates the use of the function EMERGENCY CLOSE 
GKS. Following the program example, Figure 10-1 illustrates the program’s 
effect on a VT241 workstation. 
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EMERGENCY CLOSE GKS 


Example 10-1: Executing an Emergency Closure of DEC GKS 


Cc 


c 


This program implements a user-defined error handler. 
IMPLICIT NONE 

INCLUDE ’SYS$LIBRARY:GKSDEFS.FOR’ 

INTEGER NEW_ERROR_HANDLER( 2 ), NULL, WS_ID, 

* BAD WS_ID 

DATA NULL / 0 /, WS_ID / 1 /, BAD WS ID / 69 / 


EXTERNAL HANDLE IT 


Tell GKS to use this routine instead of GKSSERROR_HANDLER. 


NEW_ERROR_HANDLER( 1 ) = %LOC( HANDLE IT ) 
NEW_ERROR_HANDLER( 2 ) = NULL 


CALL GKS$SET_ERROR_HANDLER( NEW_ERROR_HANDLER ) 


CALL GKSSOPEN_GKS( ‘SYSSERROR:’ ) 
CALL GKS$OPEN WS( WS_ID, GKS$K_CONID_ DEFAULT, GKS$K_VT240 ) 


Cause an error by passing an identifier of a workstation that 
isn’t open. 
CALL GKSSACTIVATE_WS( BAD _WS_ID ) 


CALL GKSS$DEACTIVATE WS( WS _ID ) 
CALL GKS$CLOSE_WS( WS_ID ) 
CALL GKSS$CLOSE_GKS () 

END 


HANDLE IT function. 


FUNCTION HANDLE IT( ERROR, FUNCTION_NAME, 
* ERROR‘FILE NAME ) 


INTEGER ERROR, WS_ID INVALID, WS_NOT OPEN 
CHARACTER*80 FUNCTION_NAME, ERROR_FILE_NAME 
Variables for the corresponding GKS error numbers. 
DATA WS_ID INVALID / 20 /, WS_NOT_OPEN / 25 / 
Error decision -- stop if it’s a bad workstation. 
IF ( ERROR .EQ. WS_ID INVALID .OR. 

* ERROR .EQ. WS_NOT OPEN ) THEN 


(continued on next page) 


Error-Handling Functions 10-5 


EMERGENCY CLOSE GKS 


Example 10-1 (Cont.): Executing an Emergency Closure of DEC GKS 


Cc 


aa 


Do not continue with the application. 
CALL GKS$LOG_ERROR( ERROR, FUNCTION NAME, 

* ERROR_FILE NAME ) 
WRITE (6,%) ! --r newer nnn nnn nen nnn 
WRITE (6,*) ‘SEVERE ERROR.’ 
WRITE (6,%) ! ween cnn mre nnn rrr nnn nn nna f 
WRITE(6,*) ‘After viewing the error message,’ 
WRITE (6,*) ‘Press RETURN to abort.’ 


Pause. Type RETURN when you are finished 
viewing the screen. 

READ (5, *) 

CALL GKSSEMERGENCY_CLOSE () 

STOP 


ELSE 


Continue normally by logging the error. 
CALL GKS$ERROR_HANDLER ( ERROR, FUNCTION _NAME, 
* ERROR_FILE_NAME ) 
RETURN 
END IF 
END 


The following numbers correspond to the numbers in the previous example: 


This code declares the two-element array that you need to pass to 
SET ERROR HANDLER. For more information, refer to SET ERROR 
HANDLER in this chapter. 


This is the declaration of the external error-handling function. 


In the first element of the two-element array passed to SET ERROR 
HANDLER, you assign the address of the external error-handling 
function. The second element of the array must always be zero, unless 
you are programming in Pascal (see the function description in this 
chapter). 

The call to SET ERROR HANDLER tells DEC GKS to pass control 

to the application’s error handler upon error generation. (If you do 


not implement an application-specified error handler, DEC GKS calls 
ERROR HANDLING upon error generation.) 
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All DEC GKS error handlers must have these parameters: the er- 

ror number, the function name, and the error file name. As soon as 
ACTIVATE WORKSTATION encounters the bad workstation identifier 
in the first program, DEC GKS passes control to this application-defined 
error handler. 


If the error involved a bad workstation identifier (in this example, it 
did), then this code logs the DEC GKS standard error message and then 
explains why the program aborts execution. The call to EMERGENCY 
CLOSE GKS attempts an orderly closure of DEC GKS. 


If DEC GKS generates any other error, then the call to ERROR 
HANDLING provides the standard DEC GKS response to errors: log 
the standard error message and continue with execution. 


Figure 10-1 shows the screen of a VI241 terminal after the program has 
run. to completion. 
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Figure 10-1: Executing an Emergency Closure of DEC GKS—VT241 


XGKS-E-ERROR.25, Specified workstation is not open in routine gks$activatews 


After viewing the error message, 
Press RETURN to abort. 
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ERROR HANDLING 


Operating States: GKCL, GKOP, WSOP, WSAC, SGOP 


Description 


The function ERROR HANDLING calls ERROR LOGGING and allows 
continued program execution. By default, DEC GKS calls this function when 
it encounters an error condition. 


If you choose, you can write your own error handler to replace this function. 
If you write your own error handler, you pass the address of your error- 
handling subroutine to SET ERROR HANDLER (refer to Example 10-1). 
For more information, refer to SET ERROR HANDLER in this chapter. 


For information concerning the various DEC GKS error conditions, refer to 
Appendix D, DEC GKS Error Messages. 


Format 

GKS$ERROR_HANDLER (error_number, function_name, 

error_file) 

GERHND (error_number, fun_id, error_file) 

gerrorhand (error_number, funcname, perrfile) 
Arguments 

error_number 

data type: integer 

access: read-only 

mechanism: by reference 


This argument is the number of the DEC GKS error message as dictated by 
the GKS standard or, in the case of negative error numbers, as dictated by 
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ERROR HANDLING 


the VMS implementations of GKS. To review the numbers of the DEC GKS 
error messages, refer to Appendix D, DEC GKS Error Messages. 


function_name 


data type: string 
access: read-only 
mechanism: by descriptor 


This argument is the text string containing the name of the DEC GKS 
function that detected the error. 


error_file 


data type: string 
access: read-only 
mechanism: by descriptor 


This argument is a text string containing the name of the error logging file 
that was specified in a call to OPEN GKS. 


Program Example 


For an example of a call to this function, see Example 10-1. 
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ERROR LOGGING 


Operating States: GKCL, GKOP, WSOP, WSAC, SGOP 


Description 


The function ERROR LOGGING writes the standard DEC GKS error 
message, which includes the number of the error and the text of the 
message, to the error file and returns to the procedure or function that 
called it. 


The DEC GKS supplied error handler ERROR HANDLING automatically 
calls this function. An application-supplied error handler can call this 
function if the need arises. 


Format 
GKS$LOG_ERROR (error_number, function_name, error_file) 
GERLOG (error_number, fun_id, error_file) 
gerrorlog (error_number, funcname, perrfile) 
Arguments 
error_number 
data type: integer 
access: read-only 
mechanism: by reference 


This argument is the number of the DEC GKS error message as dictated 
by the standard or, in the case of negative error numbers, as dictated by 
the VMS implementations of GKS. To review the numbers of the DEC GKS 
error messages, refer to Appendix D, DEC GKS Error Messages. 
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function_name 


data type: string 
access: read-only 
mechanism: by descriptor 


This argument is the text string containing the name of the DEC GKS 
function that detected the error. 


error_file 

data type: string 

access: read-only 
mechanism: by descriptor 


This argument is a text string containing the name of the error logging file 
that was specified in a call to OPEN GKS. 


Program Example 


For an example of a call to this function, see Example 10-1. 


10-12 Error-Handling Functions 


SET ERROR HANDLER 


SET ERROR HANDLER 


Operating States: GKCL, GKOP, WSOP, WSAC, SGOP 


Description 


The function SET ERROR HANDLER establishes an application-defined 
error handler as the function that DEC GKS calls upon error generation. 
The error handler, whose address you pass to SET ERROR HANDLER, 
replaces the DEC GKS supplied error handler ERROR HANDLING. 


Within your user-defined error handler, you can only call the DEC GKS 
functions EMERGENCY CLOSE GKS, ERROR HANDLING, ERROR 
LOGGING, or any of the inquiry functions. 


Format 

GKS$SET_ERROR_HANDLER (new_handler, [old_handler]) 
Arguments 

new_handler 

data type: bound procedure value 

access: read-only 

mechanism: by reference 


This argument is the application-defined, error-handling function or 
procedure. 


This argument is passed by bound procedure value, by reference, for the 
use of the languages that support up-level addressing (such as Pascal). If 
your language does not support up-level addressing (in languages such as 
FORTRAN or BASIC), then you must declare this argument to be an integer 
array composed of two elements. The first element must contain the address 
of the application-defined handler, and the second element must contain the 
value 0. Pass this integer array by reference. 
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old_handler 


data type: bound procedure value 
access: write-only 
mechanism: by reference 


This optional argument is the function or procedure previously used to 
handle errors. Since this value is 64 bits long, you should declare the 
argument to be an integer array of two elements, and you pass this array by 
reference. DEC GKS writes the address of the old error handler to the first 
element of your array; you can pass this array to SET ERROR HANDLER if 
at some time you want to reestablish the old error handler. 


Program Example 


For an example of a call to this function, see Example 10-1. 
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A 


Access type, 1-10 
ACCUMULATE TRANSFORMATION MATRIX, 8-31 
Accumulating 

segment transformations, 8-21 
ACTIVATE WORKSTATION, 3-15 
Activating workstations, 3~8, 3-14 
Alignment 

text, 5-84 

extent rectangle, 5-65 

Angles 


See also Segments 

rotation, 8-17 
ANSI 

GKS standard, 1—1 
Appearance 

attributes, 5-1 
Arguments 

characteristics of, 1-10 

descriptions, 1-10 

list, 2-3 

C binding, 2-3 
FORTRAN binding, 2-3 

Arrays 

color index, 4-6 
ASFs, 5-5, 5-113 
Aspect ratio, 6-18 

See also Transformations 
ASSOCIATE SEGMENT WITH WORKSTATION, 8-39 
Association 

See also Segments 

segments, 8-6 

windows and viewports, 6-6 
Asynchronous input, 7-24 

See also Input 


Attribute functions, 5—1 to 5-164 
ASFs, 5-112 to 5-115 
fill area, 5-9 to 5—28 
GKS$SET_ASF, 5-113 
GKS$SET_COLOR_REP, 5-117 
GKS$SET_FILL_COLOR_INDEX, 5-10 
GKS$SET_FILL_INDEX, 5-14 
GKS$SET_FILL_INT_STYLE, 5-19 
GKS$SET_FILL_REP, 5-122 
GKS$SET_FILL_STYLE_INDEX, 5-23 
GKS$SET_PAT_REF_PT, 5~25 
GKS$SET_PAT_REP, 5-129 
GKS$SET_PAT_SIZE, 5-27 
GKS$SET_PLINE_COLOR_INDEX, 5-38 
GKS$SET_PLINE_LINETYPE, 5-30 
GKS$SET_PLINE_LINEWIDTH, 5-34 
GKS$SET_PLINE_REP, 5-136 
GKS$SET_PMARK_COLOR_INDEX, 5-56 
GKS$SET_PMARK_REP, 5-143 
GKS$SET_PMARK_SIZE, 5-48 
GKS$SET_PMARK_TYPE, 5-52 
GKS$SET_TEXT_ALIGN, 5-84 
GKS$SET_TEXT_EXPFAC, 5-66 
GKS$SET_TEXT_FONTPREC, 5-96 
GKS$SET_TEXT_HEIGHT, 5-70 
GKS$SET_TEXT_PATH, 5~—106 
GKS$SET_TEXT_REP, 5-150 
GKS$SET_TEXT_SPACING, 5-74 
GKS$SET_TEXT_UPVEC, 5-78 
pick attributes, 5-158 to 5-164 
polyline, 5-29 to 5-46 
polymarker, 5-47 to 5-64 
representations, 5-116 to 5-157 
text, 5-65 to 5-111 

Attributes, 1-3 
Attribute Source Flags, 5-5 
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Attributes (Cont.) 
bound to primitives, 5-2 
bundled, 5-4 
GDPs, 5-4 
geometric and nongeometric, 5-2 
implicit regenerations, 5-7 
segments, 8-10 
individual, 5-4 
input prompt and echo types, 7-6 
metafiles, 9-2 
pick identification, 8-4 
segments, 8-12 
text 
extent rectangle, 5-65 
Attribute Source Flags, 5-5, 5-113 
Audit metafiles, 9-1 
AWAIT EVENT, 7-203 
Axes, 6-1 
See also Coordinates 
See also Segments 
segment fixed point, 8-17 


Background 
color, 5-7 
Binding 
attributes to primitives, 5-2 
Bindings, 1-1 
Bit masks, 2-9 
Boundaries 
See Windows or Viewports 
Break input, 7-25 
Buffers 
See also Data records 
See also Input 
input data record, 7-7 
String input, 7-4 
stroke input, 7-3 
Bundles, 5—4 
See also Attributes 
color, 5~117 
fill area, 5-14, 5-122 
pattern styles, 5-129 
polyline, 5-42, 5-136 
polymarkers, 5-60, 5-143 
text, 5-102, 5-150 


C 


Calling sequences, 2-2 
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Calls 

error handler, 10-1 

function 

reproducing, 9-3 

CALL statement, 2-2 
Categories 

See also Workstations 

workstations, 3-3 

list of, 3-4 

CELL ARRAY, 4-6 
CGM metafiles 

creating, 9-3 to 9-6 
Change vectors 

input, 7-3 

segment translation, 8-17 
Characters 

height, 5-70 

input, 7—4 

strings, 4-35 

text extent rectangle, 5-65 
Choice 

See also Input 

input class, 7-3 

specifying NOCHOICE input, 7-26, 7-29 
Circles 

using GDPs, 4-22 
Classes 

See also Input 

See also Logical input devices 

choice, 7-3 

input, 7-2 

locator, 7-3 

pick, 7-3 

string, 7-3 

stroke, 7-3 

valuator, 7-3 
Cleanup 

error handling, 10-2 
Clearing 


See also Workstations 
workstation surface, 3-18, 3-19 
implicit regeneration, 3-12 
CLEAR WORKSTATION, 3-19 
Clipping, 6-5 
See also Transformations 
pipeline 
multiple transformations, 8-26 
segments, 8-22 
text precison, 5-96 
CLOSE GKS, 3-22 


CLOSE SEGMENT, 8-41 
CLOSE WORKSTATION, 3-24 
Closing 
See also GKS 
See also Workstations 
GKS, 3-9 
error handling, 10-1 
segments, 3-8 
workstations, 3-9 
Colors 
See also Attributes 
background, 5-7 
fill area, 5-10 
foreground, 5-7 
indexes 
arrays, 4-6 
markers, 5-56 
polyline, 5-38 
representation, 5-117 
text, 5-92 
Column-major 
cell array, 4-9 
Comments 
- FORTRAN, 1-12 
Compile 
programs, 2-6 
Complement mode 
highlighting segments, 8-13 
Components 
See also Rotation 
See also Scale 
See also Translation 
segment transformations, 8-14 
Composition 
See also Transformations 
picture, 1-3 
pictures, 6—1 
Conditions 
error, 10-1 
Connection identifiers, 3-17, 3-43 
default, 3-43 
GKS$CONID, 2-7 
metafiles, 9~2 
Constants 
arguments, 2-4 
requirements, 2—5 
Continuation characters 
FORTRAN, 1-12 
Control 
error handling, 10-1 
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workstation surface, 3-11 
Control functions, 3-1 to 3-61 
GKS$ACTIVATE_WS, 3-14 
GKS$CLEAR_WS, 3-19 
GKS$CLOSE_GKS, 3-22 
GKS$CLOSE_WS, 3-24 
GKS$DEACTIVATE_WS, 3-26 
GKS$ESCAPE, 3-28 
GKS$MESSAGE, 3-34 
GKS$OPEN_GKS, 3-39 
GKS$OPEN_WS, 3-42 
GKS$REDRAW_SEG_ON_WS, 3-47 
GKS$SET_DEFER_STATE, 3-52 
GKS$UPDATE_WS, 3-59 
introduction to, 3-1 to 3-14 
metafiles, 9-2 
Coordinates 
See also Transformations 
format, 1-6 
input change vectors, 7-3 
locator and stroke input, 7-3 
maximum device, 6-12 
systems, 6-1 
used for output, 4-3 
viewport input priority, 6-10, 7~23 
Copying segments, 8-6 
COPY SEGMENT TO WORKSTATION, 8—44 
CREATE SEGMENT, 8-47 
Creating 
metafiles, 9-2 
segments, 8-2 
Current 
See also Transformations 
metafile item, 9-6 
state list entries, 5-2 
windows and viewports, 6-13 
Current event report entry, 7-35 
See also Event mode 
See also Input 
Cycling 
disabled input echo, 7-25 
logical input device control, 7~24 
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Data 
user defined, 9-7 
metafiles, 9-2 
Data declarations 
FORTRAN, 1-12 
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Data records 
See also Escapes 


See also GDPs 
See also Input 
escape/GDP 
standard, 1-7 
input, 7-7, 7-21 
prompt and echo types, 7-6 
sizes, 7-21 
standard, 7-7 
using inquiry functions, 7-21 
metafile 
item, 9-3 
returning, 1-14 
Data structures 
See also GKS 
GKS, 3-2 
Data types 
arguments, 1-10 
DCL command line 
GKS logical names, 2-7 
DEACTIVATE WORKSTATION, 3-26 
Deactivating 
See also Workstations 
workstation environment, 3-26 
workstations, 3-8 
Debug 
FORTRAN programs 
on a VT241, 1-13 
Declaring 
GKS functions 
externally, 2-3 
Defaults 
See also Attributes 
See also Transformations 
colors, 5-7 
GKS error handler, 10-9 
identity segment transformation, 8-14 
normalization window, 6-2 
unity transformation, 6~5 
Deferral 
See also Implicit regenerations 
GKS$K_ASAP, 3-53 
GKS$K_ASTI, 3-53 
GKS$K_BNIG, 3-53 
GKS$K_BNIL, 3-53 
GKS$UPDATE_WS, 3-59 
image generation 
GKS$SET_DEFER_STATE, 3-52 
output, 3-11, 4-4 
VT241, 1-13 


Index—4 


Define 
user metafile data, 9-7 
Definition files, 2-4 
including, 2-5 
list of, 2-5 
Degrees 
See also GDPs 
See also Segments 
translating to radians, 8-17 
DELETE SEGMENT, 8-49 
DELETE SEGMENT FROM WORKSTATION, 8-53 
Deleting segments, 8-2 
Deletion 
segments, 8-3 
Descriptions 
functions, 1-9 
Description tables, 3-2 
Detecting 
errors, 10-1 
segments, 8-13 
Device coordinates, 6-1 
See also Transformations 
See also Workstations 
Device dependent 
bundled attributes, 5-4 
Device independent, 3-17 
output attributes, 5-2 
Device-Independent programming 
input, 7-22 
Devices 
See also Workstations 
connection, 3-43 
default, 3-43 
logical input, 7-2 
manipulation 
GKS$ESCAPE, 3-28 
maximum coordinate values, 6-12 
Disable clipping, 6-5 
Display 
See also Workstations 
surface, 6-1 
Display surface empty entry, 3-47, 3-59 
Dynamic modification 
See also Implicit regeneration 
attributes, 3-12 
workstation transformations, 3-12 
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Echo 
See also Input 
cycling and disabled echo, 7-25 
input values, 7-24 
prompt and echo types, 7-6 
Emergency 
closure of GKS, 10-1 
EMERGENCY CLOSE GKS, 10-4 
Enable clipping, 6-5 
Ending 
GKS program, 3-22 
Entries 
See also GKS 
bundle table, 5-4 
bundle tables, 5—4 
GKS state list 
output attributes, 5-2 
Environment 
GKS, 3-1 
workstation, 3-1 
Error handling 
GKS, 1-4 . 
ERROR HANDLING, 10-9 
Error-handling functions, 10-1 to 10-14 
GKS$EMERGENCY_CLOSE, 10-4 
GKS$ERROR_HANDLER, 10-9 
GKS$LOG_ERROR, 10-11 
GKS$SET_ERROR_HANDLER, 10-13 
introduction to, 10-1 to 10-3 
ERROR LOGGING, 10~11 
Errors 
file, 10-2 
logging, 3-6, 10-11 
state list, 3-39 
states, 10-2 
Status files, 2-4 
Error status files 
list of, 2-6 
ESCAPE, 3-28 
Escapes 
data records, 1-7 
GKSS$ESCAPE, 3-28 
EVALUATE TRANSFORMATION MATRIX, 8-57 
Event input queue, 7-34 
overflow, 7-52 
Event mode, 7-34 to 7-55 
See also Input 
cycling devices, 7-24 
multiple device use, 7-41 
simultaneous events, 7-41 


Executing 
programs, 2-6 
Expansion 
See also Scale 
See also Segments 
segments, 8-17 
text, 5-66 
Extent rectangle, 5-65 
See also Attributes 
See also Segments 
See also Text 
segments 
highlighting, 8-13 
External functions 
declaring GKS functions, 2-3 
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Fatal errors, 10—1 
Figures 
format, 1-13 
Files 
definition, 2~4 
list of, 2-5 
error, 10-2 
error status, 2-4 
list of, 2-6 
metafiles, 9—1 
File specifications 
connection id 
default, 3-43 
metafiles, 9-2 
FILL AREA, 4-18 
Fill areas 
See also Attributes © 
bundles, 5-14 
interior styles, 5—19 
representation, 5-122 
style indexes, 5-23 
Fixed points 
See also Rotation 
See also Scale 
See also Segments 
segment transformations, 8-17 
Flags 
See also Attributes 
attribute source, 5-5, 5-113 
Flush 
Event queue, 7-35 
FLUSH DEVICE EVENTS, 7-207 
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Fonts 

establishing, 5-96 
Foreground color, 5—7 
Format 

function descriptions, 1-9 

metafiles, 9-3 
FORTRAN 

constructs, 1-12 
FORTRAN binding, 1-1 

linking programs 

VMS, 2-6 

Functional standards 

See also GKS 
Functions 

See also GKS 

attribute, 5-1 

DEC GKS categories, 1-2 

descriptions, 1~9 

error handling, 10-1 

escape, 3-28 

external 

declaring, 2-3 

identifiers, 2-3 

input, 7-1 

presentation, 1-9 to 1-13 

segments, 8—1 

transformation, 6—1 

utility, 8~18 
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GDPs, 4~22 to 4-26 

circles, 4—22 

data records, 1-7 

output attributes, 5-4 
GENERALIZED DRAWING PRIMITIVE, 4-22 
Generalized drawing primitives 

See GDP 
Generation 

See also Output 

output, 4-1 

attributes, 5—1 

pictures, 6-1 
Geometric attributes, 5-2 
GET CHOICE, 7-210 
GET ITEM TYPE FROM GKSM, 9-13 
GET LOCATOR, 7-217 
GET PICK, 7-219 
GET STRING, 7-221 
GET STROKE, 7-228 
GET VALUATOR, 7-235 
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GKS 
ANSI and ISO standards, 1-1 
categories of functions, 1-2 
closing, 3-9. 
data structures, 3-2 
description table, 3-2 
environment, 3-1, 3-22 
initialization of, 3-39 
error handling, 1-4, 10-1 
HELP, 2~2 
input 
levels of, 1-4 
introduction to, 1-1 to 1-6 
kernel, 3~2 
levels, 1-4 
logical names, 2-7 
metafile standard, 9-1 
opening, 3-6 
output 
levels of, 1-4 
programming, 2-1 to 2-9 
release notes, 2-2 
state list 
output attributes, 5-2 
GKS$ACCUM_XFORM_MATRIX, 8-31 to 8-38 
GKS$ACTIVATE_WS, 3-14 to 3-18 
GKS$ASSOC_SEG_WITH_WS, 8-39 to 8-40 
GKS$AWAIT_EVENT, 7-35, 7-203 to 7-206 
example, 7-36 
GKS$CELL_ARRAY, 4-6 to 4-17 
GKS$CLEAR_WS, 3-19 to 3-21 
GKS$CLOSE_GKS, 3-22 to 3-23 
GKS$CLOSE_SEG, 8-41 to 8-43 
GKS$CLOSE_WS, 3-24 to 3-25 
GKS$CONID, 2-7, 3-17, 3-43 
GKS$COPY_SEG_TO_WS, 8-44 to 8-46 
GKS$CREATE_SEG, 8-47 to 8-48 
GKS$DEACTIVATE_WS, 3-26 to 3-27 
GKS$DELETE_SEG, 8-49 to 8-52 
GKS$DELETE_SEG_FROM_WS, 8-53 to 8-56 
GKS$EMERGENCY_CLOSE, 10-4 to 10-8 
GKS$ERROR_HANDLER, 10-9 to 10-10 
GKS$ESCAPE, 3-28 to 3-33 
GKS$EVAL_XFORM_MATRIX, 8-57 to 8-60 
GKS$FILL_AREA, 4-18 to 4—21 
GKS$FLUSH_DEVICE_EVENTS, 7-35, 7-53, 7-207 
to 7-209 
example, 7-54 
GKS$GDP, 4-22 to 4-26 
GKS$GET_CHOICE, 7-210 to 7-216 
GKS$GET_ITEM, 9-13 to 9-15 


GKS$GET_LOCATOR, 7~217 to 7-218 
example, 7-36 
GKS$GET_PICK, 7-219 to 7-220 
example, 7-42 
GKS$GET_STRING, 7-221 to 7-227 
GKS$GET_STROKE, 7-228 to 7-234 
GKS$GET_VALUATOR, 7-235 to 7~236 
example, 7-42 
GKS$INIT_CHOICE, 7-58 to 7-65 
GKSS$INIT_LOCATOR, 7-67 to 7-71 
GKS$INIT_PICK, 7-72 to 7-79 
GKS$INIT_STRING, 7-81 to 7-87 
GKSS$INIT_STROKE, 7-88 to 7-95 
GKS$INIT_VALUATOR, 7-97 to 7-102 
GKS$INQ_INPUT_QUEUE_OVERFLOW, 7-52 
example, 7-42 
GKS$INQ_MORE_SIMUL_EVENTS 
example, 7-42 
GKS$INSERT_SEG, 8-61 to 8-66 
GKS$INTERPRET_ITEM, 9-16 to 9-18 
GKS$K_ASAP, 1-13 
GKS$K_CONID_DEFAULT, 3-17, 3-43 
GKS$K_PERFORM_FLAG, 3-60 
GKS$K_POSTPONE_FLAG, 3-60 
GKS$K_WSTYPE_DEFAULT, 3-44 
GKS$LOG_ERROR, 10-11 to 10-12 
GKS$MESSAGE, 3-34 to 3-38 
GKS$OPEN_GKS, 3-39 to 3-41 
GKS$OPEN_WS, 3-42 to 3-46 
GKS$POLYLINE, 4~27 to 4-30 
GKS$POLYMARKER, 4-31 to 4-34 
GKS$READ_ITEM, 9-19 to 9-21 
GKS$REDRAW_SEG_ON_WS, 3-47 to 3-51 
GKS$RENAME_SEG, 8-67 to 8~70 
GKS$REQUEST_CHOICE, 7-124 to 7-126 
GKS$REQUEST_LOCATOR, 7~127 to 7-130 
example, 7-26 
GKS$REQUEST_PICK, 7-131 to 7-133 
GKS$REQUEST_STRING, 7-134 to 7-137 
GKS$REQUEST_STROKE, 7-138 to 7-141 
GKS$REQUEST_VALUATOR, 7-142 to 7-144 
GKS$SAMPLE_CHOICE, 7-146 to 7-155 
GKS$SAMPLE_LOCATOR, 7-156 to 7-158 
example, 7-29 
GKS$SAMPLE_PICK, 7-159 to 7-168 
GKS$SAMPLE_STRING, 7-169 to 7-179 
GKS$SAMPLE_STROKE, 7-180 to 7-193 
GKS$SAMPLE_VALUATOR, 7-194 to 7-201 
GKS$SELECT_XFORM, 6-21 to 6-25 
GKS$SET_ASF, 5-113 to 5-115 
GKS$SET_CHOICE_MODE, 7-105 to 7-107 


GKS$SET_CLIPPING, 6-26 to 6-29 
GKS$SET_COLOR_REP, 5-117 to 5-121 
GKS$SET_DEFER_STATE, 3-52 to 3-58 
GKS$SET_ERROR_HANDLER, 10-13 to 10-14 
GKS$SET_FILL_COLOR_INDEX, 5-10 to 5-13 
GKS$SET_FILL_INDEX, 5-14 to 5-18 
GKS$SET_FILL_INT_STYLE, 5-19 to 5-22 
GKS$SET_FILL_REP, 5-122 to 5-128 
GKS$SET_FILL_STYLE_INDEX, 5-23 to 5-24 
GKS$SET_LOCATOR MODE, 7-108 to 7-110 
GKS$SET_PAT_REF_PT, 5-25 to 5-26 
GKS$SET_PAT_REP, 5-129 to 5-135 
GKS$SET_PAT SIZE, 5-27 to 5-28 
GKS$SET_PICK_ID, 5-159 to 5-164 
GKS$SET_PICK_MODE, 7-111 to 7-113 
GKS$SET_PLINE_COLOR_INDEX, 5-38 to 5-41 
GKS$SET_PLINE_INDEX, 5-42 to 546 
GKS$SET_PLINE_LINETYPE, 5-30 to 5-33 
GKS$SET_PLINE_LINEWIDTH, 5-34 to 5-37 
GKS$SET_PLINE_REP, 5-136 to 5-142. 
GKS$SET_PMARK_COLOR_INDEX, 5-56 to 5-59 
GKS$SET_PMARK_INDEX, 5-60 to 5-64 
GKS$SET_PMARK_REP, 5-143 to 5-149 
GKS$SET_PMARK_SIZE, 5-48 to 5-51 
GKS$SET_PMARK_TYPE, 5-52 to 5-55 
GKS$SET_SEG_DETECTABILITY, 8-71 to 8-75 
GKS$SET_SEG_HIGHLIGHTING, 8-77 to 8-80 
GKS$SET_SEG_PRIORITY, 8-81 to 8-86 
GKS$SET_SEG_VISIBILITY, 8-90 to 8-93 
GKS$SET_SEG_XFORM, 8-87 to 8-89 
GKS$SET_STRING_MODE, 7-114 to 7-116 
GKS$SET_STROKE_MODE, 7~117 to 7-119 
GKS$SET_TEXT_ALIGN, 5-84 to 5-91 
GKS$SET_TEXT_COLOR_INDEX, 5-92 to 5-95 
GKS$SET_TEXT_EXPFAC, 5-66 to 5-69 
GKS$SET_TEXT_FONTPREC, 5-96 to 5-101 
GKS$SET_TEXT_HEIGHT, 5-70 to 5-73 
GKS$SET_TEXT_INDEX, 5-102 to 5-105 
GKS$SET_TEXT_PATH, 5-106 to 5-111 
GKS$SET_TEXT_REP, 5-150 to 5-157 
GKS$SET_TEXT_SPACING, 5-74 to 5-77 
GKS$SET_TEXT_UPVEC, 5-78 to 5-83 
GKS$SET_VALUATOR_MODE, 7-120 to 7-122 
GKS$SET_VIEWPORT, 6-31 to 6-34 
GKS$SET_VIEWPORT_PRIORITY, 6-35 to 6-41 
GKS$SET_WINDOW, 6-43 to 6-45 
GKS$SET_WS_VIEWPORT, 6-46 to 6-51 
GKS$SET_WS_WINDOW, 6-53 to 6-58 
GKS$TEXT, 4-35 to 4-38 

GKS$UPDATE_WS, 3-59 to 3-61 
GKS$WRITE_ITEM, 9-22 to 9-24 
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GKS$WSTYPE, 2-7, 3-44 
GKSM metafiles, 9-1 

creating, 9-2 to 9-3 
Graphics 

interactive, 7-1 
Graphics handlers, 3-2 

See also Devices 

See also Workstations 

input, 7-6 

interactive 

See also Input 
nominal sizes, 5-3 


H 


Handlers, 3-2 

See also Devices 

See also Workstations 

errors, 10-1 

input, 7-6 

nominal sizes, 5-3 
Hardware fonts, 5-96 

See also Fonts 
Hatches, 5—19 

See also Fill areas 

fill areas, 4-18 

style index values, 5-23 
Height 

See also Attributes 

See also Transformations 

text, 5-70 

to width ratio, 6-18 
HELP 

GKS, 2-2 
Hexadecimal 

workstation type value, 2-9 
Highlighting 

segments, 8-13 
Hollow 

fill area interior style, 5-19 

fill areas, 4-18 


Identifiers 

pick, 7-4, 8-4 

workstation, 3-17 
Identity 

segment transformation, 8-18 
Implicit regenerations, 3-12 
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Implicit regenerations (Cont.) 
See also Deferral 
attribute changes, 5-7 
GKS$REDRAW_SEG_ON_WS, 3-47 
segments, 8-10 
workstation transformations, 6-13 
Include 
definition files, 2-5 
files, 2-4 
INCLUDE statement 
all languages, 2-5 
Indexes 
See also Attributes 
See also Bundles 
color, 5-117 
arrays, 4-6 
fill area, 5-14, 5-122 
styles, 5-23 
interior style, 4-20 
into bundle tables, 5-4 
pattern styles, 5-129 
polyline, 5-136 
polymarkers, 5-143 
text, 5-102, 5—150 
Individual attributes, 5-4 
Initialize 
See also GKS 
See also Workstations 
GKS environment, 3-39 
workstation environment, 3-42 
INITIALIZE CHOICE, 7-58 
INITIALIZE LOCATOR, 7-67 
INITIALIZE PICK, 7-72 
INITIALIZE STRING, 7-81 
INITIALIZE STROKE, 7-88 
INITIALIZE VALUATOR, 7-97 
Initial string 
input, 7-4 
Input 
asynchronous, 7-24 
breaking, 7-25 
classes, 7-2, 7-3 
current values, 7-21 
cycling device control, 7-24 
data record 
sizes, 7-21 
using inquiry functions, 7-21 
data records 
standard, 7-7 
default values, 7-21 
device-independent programming, 7-22 


Input (Cont.) 
event mode, 7-34 to 7-55 
flushing the queue, 7-35 
simultaneous events, 7-41 
event queue, 7-34 
event queue overflow, 7-52 
inquiry function use, 7-21 
logical device number, 7-2 
logical devices, 7-2 
measure, 7-2 
menus, 7—4 
metafiles, 9-1, 9-2 
operating modes, 7-24 to 7-55 
physical devices, 7—2 
pick 
visibility, 8-29 
pick identification, 8—4 
request mode, 7-25 to 7-28 
sample mode, 7-28 to 7-34 
segment detectability, 8~13 
segments, 8-4 
specifying no input, 7-25 
synchronous, 7-24 
text, 7-4 
triggers, 7-3, 7-25 
viewport priority, 6-10, 7-23 
workstation category, 3-4 
Input data record 
sizes, 7-21 
Input data records 
standard list, 7-7 to 7-20 
Input functions, 7-1 to 7-236 
function descriptions, 7-56 to 7-236 
GKS$AWAIT_EVENT, 7-203 
GKS$FLUSH_DEVICE_EVENTS, 7-207 
GKS$GET_CHOICE, 7-210 
GKS$GET_LOCATOR, 7-217 
GKS$GET_PICK, 7-219 
GKS$GET_STRING, 7-221 
GKS$GET_STROKE, 7-228 
GKS$GET_VALUATOR, 7-235 
GKSS$INIT_CHOICE, 7-58 
GKS$INIT_LOCATOR, 7-67 
GKS$INIT_PICK, 7-72 
GKSSINIT_STRING, 7-81 
GKSS$INIT_STROKE, 7-88 
GKSS$INIT_VALUATOR, 7-97 
GKS$REQUEST_CHOICE, 7-124 
GKS$REQUEST_LOCATOR, 7-127 
GKS$REQUEST_PICK, 7-131 
GKS$REQUEST_STRING, 7-134 


Input functions (Cont.) 
GKS$REQUEST_STROKE, 7-138 
GKS$REQUEST_VALUATOR, 7-142 
GKS$SAMPLE_CHOICE, 7-146 
GKS$SAMPLE_LOCATOR, 7-156 
GKS$SAMPLE_PICK, 7-159 
GKS$SAMPLE_STRING, 7-169 
GKS$SAMPLE_STROKE, 7-180 
GKS$SAMPLE_VALUATOR, 7-194 
GKS$SET_CHOICE_ MODE, 7-105 
GKS$SET_LOCATOR_MODE, 7-108 
GKS$SET_PICK_ID, 5-159 
GKS$SET_PICK_MODE, 7-111 
GKS$SET_STRING_MODE, 7-114 
GKS$SET_STROKE_MODE, 7-117 
GKS$SET_VALUATOR_MODE, 7-120 
introduction to, 7-1 to 7-55 

Input operating modes, 7-24 

Inquiry functions 
input use, 7-21 

Inserting segments, 8-6 

INSERT SEGMENT, 8-61 

Interactive graphics, 7-1 
See also Input 

Interface 
prompt and echo types, 7-6 

Interior styles, 4-20 
See also Attributes 
See also Hatches 
See also Patterns 
of fill areas, 5-19 

Interpret 
metafiles, 9-1 

INTERPRET ITEM, 9-16 

Items 
metafile header, 9-3 


K 


Kernel 
GKS, 3-2 


L 


Languages 
argument data types, 2-3 
bindings, 1-1 
calling sequences, 2-2 
declaring external functions, 2-3 
GKS, 2-1 
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Lengths 
See also Data records 
See also Input 
input data records, 7-7 
metafile data record, 9-6 
Levels 
of GKS, 1-4 
Lines 
See also Attributes 
See also Output 
generating, 4-27 
type, 1-3 
types, 5-30 
width, 5-34 
Linking, 2-6 
VMS 
FORTRAN binding, 2-6 
Lists 
See also GKS 
See also Input 


See also Workstations 

argument, 2-3 

viewport input priority, 6-11, 7-23 
Locator 

input class, 7-3 

viewport input priority, 6-10, 7-23 
Logging 

errors, 10-11 
Logical input devices, 7-2. 

See also Input 

number, 7-2 
Logical names 

GKS programming, 2-7 


Mapping 

See also Transformations 

aspect ratio, 6-18 

cell array 

direction, 4~8 

color indexes, 4—6 

workstation transformations, 6-12 
Markers, 4-31 

See also Attributes 

See also Output 


size, 5-48 
types, 5-52 
Matrix 


See also Rotation 
See also Scale 
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Matrix (Cont.) 
See also Translation 
segment transformation, 8-18 
Measure 
See also Logical input devices 
cycling input device control, 7-24 
input device, 7-2 
Menus 
See also Choice 
input, 7-4 
MESSAGE, 3-34 
Messages 
See also Errors 
logging errors, 10-1 
produced by error handler, 10-1 
sent to workstations, 3-34 
Metafile functions, 9-1 to 9-24 
GKS$GET_ITEM, 9-13 
GKS$INTERPRET_ITEM, 9-16 
GKS$READ_ITEM, 9-19 
GKS$WRITE_ITEM, 9-22 
introduction to, 9-1 to 9-11 
Metafiles, 1-4 
creating, 9-3 
creating CGM metafiles, 9-3 
current item, 9-6 
item header, 9-3 
reading, 9-6 to 9-7 
reproducing pictures, 9-1 
structure, 9-3 
user-defined data, 9-7 
workstation categories, 3~4 
Mirror images 
cell arrays, 4-6 
Modes 
See also Input 
Event, 7-24 
input operating, 7-24 
Request, 7-24 
Sample, 7-24 
Multiple transformations, 8-26 
See also Segments 


See also Transformations 


Names 
error messages, 10-1 
segment, 8-2 

NDC, 6-1 
See also Transformations 


NDC (Cont.) 
fixed points, 8-17 
New frame necessary at update entry, 8-10 
New frame necessary entry, 3-47 
Nominal sizes, 5-3 
Nongeometric attributes, 5-2 
See also Attributes 
Normalization 
clipping, 6-5 
overlapping viewports, 6-10 
transformations, 1-3 
maximum number, 6-6 
viewports, 6-5 
windows, 6-2 
Normalization transformations 
See also Transformations 
Normalized device coordinates 
See NDC 
Numbers 
See also Errors 
See also Input 
error messages 
handling, 10-1 
logical device, 7-2 


O 


OFF 

error state, 10-2 
Offset 

cell array, 4-7 
ON 

error state, 10-2 
One-to-one _ 

_ See also Mapping 


transformations, 6-18 
OPEN GKS, 3-39 
Opening 

GKS, 3-6 

GKSM metafile workstations, 9-2 

segments, 3-8, 8-3 

workstations, 3-7, 3-17 
OPEN WORKSTATION, 3-42 
Operating modes 

input, 7-24 to 7-55 
Operating states, 3-5 

using output, 4-2 
Operating system 

VMS, 2-1 
Order 

See also Transformations 


Order (Cont.) 

multiple transformations, 8-26 

viewport input priority, 6-11 
Origin 

See also Transformations 

world coordinate system, 6-2 
Output 

See also Attributes 

altering the primitive, 4-3 

attribute functions 

See also Attribute Functions, 5-1 

attributes, 1-3, 4-3 

bound attributes, 5-2 

default windows and viewports, 4-3 

deferral, 3-11, 4-4 

VT241, 1-13 

list of primitives, 1-2 

lost during transformations, 6-13 

metafiles, 9-1, 9-2 

pick identification, 8-4 

pictures, 6-1 

segments, 8—1 

valid operating states, 4-2 

workstation categories, 4~2 

workstation category, 3-4 
Output functions, 4~1 to 4-38 

descriptions of, 4-5 to 4-38 

GKS$CELL_ARRAY, 4-6 to 4-17 

GKS$FILL_AREA, 4-18 

GKS$POLYLINE, 4-27 

GKS$POLYMARKER, 4-31 

GKS$TEXT, 4-35 

introduction to, 4-1 to 4-4 
Overflow 

event input queue, 7-52 
Overlapping 

See also Transformations 

segments, 8-14 

viewports, 6-10 
Overlapping viewports, 7-23 


p 


Passing mechanisms 
arguments, 1-10 
Pasteboard 
See also Transformations 
normalization viewport, 6-5 
Path 
See also Text 
text, 5-106 
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Patterns, 5-19 
See also Attributes 
fill areas, 4~18 
reference points, 5-25 
representation, 5-129 
specifying size, 5-27 
style index values, 5-23 
Pending 
See also Implicit regenerations 
bundle changes, 3~12 
output generation, 3~11 
segment attribute changes, 3-12 
workstation transformations, 3-12 
pi, 8-17 
See also GDPs 
See also Segments 
Pick 
See also Input 
See also Segments 
identifier, 7-4, 8-4 
input class, 7-3 
segment detectability, 8-13 
specifying NOPICK input, 7-26, 7~29 
visibility, 8-29 
Pictures 
See also Output 


See also Transformations 
composition, 1-3, 6-1 
reproducing 
metafiles, 9-1 
shape, 6-18 
Pipeline 
See also Segments 
multiple transformations, 8-26 
Plotting 
See also Transformations 
pictures, 6-1 
Pointers 
See also Bundles 
into bundle tables, 5-4 
Points 
See also Transformations 
coordinate, 6-1 
pattern reference, 5-25 
segments 
fixed points, 8-17 
viewport input priority, 6-10 
Polygons 
See also Attributes 


Index—12 


Polygons (Cont.) 
See also Output 
fill areas, 4-18 
using GKS$POLYLINE, 4-27 
Polyline 
line type, 1-3 
POLYLINE, 4-27 
Polylines 


See also Attributes 

See also Output 

bundles, 5-42 

line type, 5-30 

representation, 5-136 
POLYMARKER, 4-31 
Polymarkers 

See also Output 

See also Transformations 

bundle table, 5-60 

representation, 5-143 
Positioning 

primitives, 6-7 

relative, 6-18 
Precision text 

establishing, 5-96 
Presentation 

See also Transformations 

pictures, 6-12 
Primitives 

See also Attributes 

See also Output 

bound attributes, 5-2 

clipping segments, 8-22 

highlighting, 8-13 

input prompt and echo types, 7-6 

list, 1-2 

lost during regeneration, 3-12 

lost during transformations, 6-13 

output, 4-1 to 4-4 

output attributes, 5-1 

pick identification, 8-4 

reproducing 

metafiles, 9-1 

segment detectability, 8-13 

segments, 8-1 

transformation, 6-2 
Priority 

See also Input 

segments, 8-14 

viewport input, 6-10, 7-23 
Programming 

See also GKS 


Programming (Cont.) 
device independency, 3-17 
device-independent input, 7-22 
error handling, 10-1 
GKS, 2-1 
Programs 
examples 
format, 1-11 
execution of, 2-6 
logical names, 2-7 
pausing, 1-13 
Prompt and echo types, 7-6 
See also Input 
standard data records, 7-7 
Proportionate 
See also Transformations 
aspect ratio, 6-18 


Q 


Queue 
event input, 7-34 


R 


Radians 
Translating to degrees, 8-17 
Ranges 


See also Transformations 
coordinate format, 1-6 
windows and viewports, 6-2 
Ratio 
See also Transformations 
aspect, 6-18 
Reading a metafile, 9-6 
READ ITEM FROM GKSM, 9-19 
READ statement 
in FORTRAN, 1-13 
Real numbers 
input, 7—4 
Records 
See also Escapes 
See also GDPs 
See also Input 
escape/GDP data, 1-7 
input, 7-7 
prompt and echo types, 7-6 
standard, 7-7 
Rectangles 
See also Attributes 


Rectangles (Cont.) 
See also Transformations 
clipping, 6-5 
segments, 8-22 
text extent, 5-65 
REDRAW ALL SEGMENTS ON WORKSTATION, 
3-47 
Regenerations 
controlling 
GKS$SET_DEFER_STATE, 3-52 
GKS$UPDATE_WS, 3-59 
segments, 8-10 
workstation surface, 3-12 
workstation transformations, 6-13 
Relative positioning, 6-18 
Release notes 
GKS, 2-2 
Releasing DEC GKS buffers, 3-22 
RENAME SEGMENT, 8-67 
Renaming 
segments, 8-3 
Reports 
current event on input queue, 7-34 
Representations 


See also Attributes 
bundle table entries, 5-5 
color, 5-117 
fill area, 5-122 
functions, 5-7, 5-116 
implicit regenerations, 5-7 
pattern, 5-129 
polyline, 5-136 
polymarker, 5-143 
text, 5-150 
Reproducing 
metafiles, 9-1 
REQUEST CHOICE, 7-124 
REQUEST LOCATOR, 7-127 
Request mode, 7-25 to 7-28 


See also Input 

breaking, 7-25 
REQUEST PICK, 7-131 
REQUEST STRING, 7-134 
REQUEST STROKE, 7-138 
REQUEST VALUATOR, 7-142 
Reverse video 

highlighting segments, 8-13 
Rotation 

fixed points, 8-17 

segments, 8-14 
RUN DCL command, 2-6 
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S 


SAMPLE CHOICE, 7-146 
SAMPLE LOCATOR, 7-156 
Sample mode, 7-28 to 7-34 
SAMPLE PICK, 7~159 
SAMPLE STRING, 7-169 
SAMPLE STROKE, 7-180 
SAMPLE VALUATOR, 7-194 
Scale 

See also Segments 

fixed points, 8-17 

segments, 8-14 

valuator input, 7-4 
Scale factors, 5-3 
Scraich pad 


See also Transformations 
normalization window, 6-5 
Segment functions, 8-1 to 8-93 
GKS$ACCUM_XFORM_MATRIX, 8-31 
GKS$ASSOC_SEG_WITH_WS, 8-39 
GKS$CLOSE_SEG, 8-41 
GKS$COPY_SEG_TO_WS, 8-44 
GKS$CREATE_SEG, 8-47 
GKS$DELETE_SEG, 8-49 
GKS$DELETE_SEG_FROM_WS, 8-53 
GKS$EVAL_XFORM_MATRIX, 8-57 
GKS$INSERT_SEG, 8-61 
GKS$RENAME_SEG, 8-67 
GKS$SET_SEG_DETECTABILITY, 8-71 
GKS$SET_SEG_HIGHLIGHTING, 8-77 
GKS$SET_SEG_PRIORITY, 8-81 
GKS$SET_SEG_VISIBILITY, 8-90 
GKS$SET_SEG_XFORM, 8-87 
introduction to, 8-1 to 8-29 
Segments 
accumulated transformations, 8-21 
associating, 8-6 
attributes, 8-12 
clipping, 8-22 
closing, 3-8 
copying, 8-6 
creating, 8-2 
deleting, 8-2 
deletion, 8-3 
detectability, 8-13 
highlighting, 8-13 
input, 8-4 
inserting, 8-6 
metafiles, 9-2 
names, 8-2 
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Segments (Cont.) 
opening, 3-8, 8-3 
order of transformation, 8-21 
overlapping, 8-14 
priority, 8-14 
redrawing, 3-47 
redrawn, 3-12 
renaming, 8-3 
rotating, 8-14 
scaling, 8-14 
selecting a transformation, 8-18 
state list, 3-47, 8-3 
storage, 8-6 
surface update, 8-10 
transformation matrix, 8-18 
transformations, 8-14 to 8-28 
translating, 8-14 
visibility, 8-29 
WDSS, 8-6 
WISS, 8-6 
SELECT NORMALIZATION TRANSFORMATION, 
6-21 
SET ASPECT SOURCE FLAGS, 5-113 
SET CHARACTER EXPANSION FACTOR, 5-66 
SET CHARACTER HEIGHT, 5-70 
SET CHARACTER SPACING, 5-74 
SET CHARACTER UP VECTOR, 5-78 
SET CHOICE MODE, 7—105 
SET CLIPPING INDICATOR, 6-26 
SET COLOR REPRESENTATION, 5-117 
SET DEFERRAL STATE, 3-52 
SET DETECTABILITY, 8-71 
SET ERROR HANDLER, 10-13 
SET FILL AREA COLOR INDEX, 5-10 
SET FILL AREA INDEX, 5-14 
SET FILL AREA INTERIOR STYLE, 5-19 
SET FILL AREA REPRESENTATION, 5-122 
SET FILL AREA STYLE INDEX, 5-23 
SET HIGHLIGHTING, 8-77 
SET LINETYPE, 5-30 
SET LINEWIDTH SCALE FACTOR, 5-34 
SET LOCATOR MODE, 7-108 
SET MARKER SIZE SCALE FACTOR, 5-48 
SET MARKER TYPE, 5-52 
SET PATTERN REFERENCE POINT, 5-25 
SET PATTERN REPRESENTATION, 5-129 
SET PATTERN SIZE, 5-27 
SET PICK ID, 5-159 
SET PICK MODE, 7-111 
SET POLYLINE COLOR INDEX, 5-38 
SET POLYLINE INDEX, 5-42 


SET POLYLINE REPRESENTATION, 5-136 
SET POLYMARKER COLOR INDEX, 5-56 
SET POLYMARKER INDEX, 5-60 
SET POLYMARKER REPRESENTATION, 5-143 
SET SEGMENT PRIORITY, 8-81 
SET SEGMENT TRANSFORMATION, 8-87 
SET STRING MODE, 7-114 
SET STROKE MODE, 7-117 
SET TEXT ALIGNMENT, 5-84 
SET TEXT COLOR INDEX, 5-92 
SET TEXT FONT AND PRECISION, 5-96 
SET TEXT INDEX, 5-102 
SET TEXT PATH, 5-106 
SET TEXT REPRESENTATION, 5—150 
Settings 
See also Attributes 
See also Transformations 
attribute values, 5-1 
pattern sizes, 5-27 
segment transformations, 8-18 
windows and viewports, 6-3 
SET VALUATOR MODE, 7-120 
SET VIEWPORT, 6-31 
SET VIEWPORT INPUT PRIORITY, 6-35 
SET VISIBILITY, 8-90 
SET WINDOW, 6-43 
SET WORKSTATION VIEWPORT, 6-46 
SET WORKSTATION WINDOW, 6-53 
Shape 
picture, 6-18 
Shareable image library 
GKS functions, 2-6 
Shift segments, 8-14 
Shrink segments, 8-17 
Simultaneous events, 7-41 
See also Input 
Sizes 
input data record, 7~21 
markers, 5-48 
patterns, 5-27 
segments, 8-17 
Software fonts, 5-96 
Solid 
See also Attributes 
fill area interior style, 5~19 
fill areas, 4-18 
Spacing text, 5-74 
Standards 
See also ANSI 
See also GKS 
DEC GKS escape/GDP data records, 1-7 


Standards (Cont.) 
functional vs. syntactical, 1—1 
input data records, 7-7 
Input data records, 7-7 to 7-20 
metafiles, 9-1 
State lists 
DEC GKS, 8-3 
GKS, 3-5 
initializing, 3-39 
output attributes, 5-2 
segment, 3-5, 8-3 
surface control entries, 3-13 
workstation, 3-5 
attributes, 5—4 
initialization of, 3-42 
Statements 
CALL, 2-2 
INCLUDE, 2-5 
READ, 1-13° 
States 
error, 10-2 
operating, 3-5 
Storage 
metafiles, 1-4, 9-1 
segments, 8-6 
Strings 
See also Text 
declaring 
FORTRAN, 1-12 
input class, 7~3 
text extent rectangle, 5-65 
Stroke 
input class, 7-3 
viewport input priority, 7-23 
viewport priority, 6-10 
Structure 
metafiles, 9-3 
Styles 
See also Attributes 
fill areas, 5-23 
Surface 
See also Implicit regenerations 
control, 3-11 
foreground and background colors, 5-7 
implicit regenerations 
attribute changes, 5-7 
regeneration, 3-12 
state list entries, 3-13 
update 
segments, 8-10 
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Symbols 


polymarkers, 4-31 
Synchronous input, 7-24 


See also Input 
Syntactical standards 

See also FORTRAN binding 
Syntax 

format, 1-9 
SYS$ERROR, 2-7, 3-7, 3-17, 3-39 
SYS$OUTPUT, 3-43 


Tr 


Tables 
See also Attributes 
See also Bundles 
attribute bundle, 5-4 
color index, 5-117 
fill area bundle index, 5-122 
pattern style bundle index, 5-129 
polyline bundle index, 5-136 
polymarker bundle index, 5-143 
text bundle index, 5-150 
Terminating 
error handling, 10-1 
GKS environment, 3-22 
request input, 7-25 
workstation environment, 3-24 
Text 
See also Attributes 
See also GKS$TEXT 
alignment, 5-84 
attributes, 4-35 
bundles, 5~102 
character width, 5-66 
expansion factor, 5-66 
extent rectangle, 5-65 
fonts, 5-96 
height, 5-70 
input, 7—4 
path, 5-106 
precision, 5-96 
representation, 5-150 
spacing, 5-74 
up-vector, 5-78 
TEXT, 4-35 
Time input vector, 7-3 
Toggling 
logical input device control, 7-24 
Transformation functions, 6-1 to 6-58 
GKS$SELECT_XFORM, 6-21 
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Transformation functions (Cont.) 


GKS$SET_CLIPPING, 6-26 
GKS$SET_VIEWPORT, 6-31 
GKS$SET_VIEWPORT_PRIORITY, 6-35 
GKS$SET_WINDOW, 6-43 
GKS$SET_WS_VIEWPORT, 6-46 
GKS$SET_WS_WINDOW, 6-53 
introduction to, 6—1 to 6-20 
Transformations 
aspect ratio, 6-18 
deferred 
placed into effect, 3-47 
entire process, 6-14 
identity (segment), 8-18 
implicit regenerations, 6-13 
input change vectors, 7-3 
metafiles, 9-2 
multiple, 8-26 
normalization, 1-3, 6-2 to 6-12 
clipping, 6-5 
maximum number, 6-6 
overlapping viewports, 6-10 
text height, 5-70 
normalization viewports, 6-5 
normalization windows, 6-2 
overlapping viewports, 7-23 
relative positioning, 6-18 
segments, 8-14 to 8-28 
accumulating, 8-21 
fixed points, 8-17 
matrix, 8-18 
unity, 6-5 
used for output, 4-3 
used in input, 7-3 
viewport input priority, 7-23 
workstation, 1-3, 6-12 
Translations 
segments, 8-14 
viewport input priority, 6-10 
Transporting 
metafiles, 9-1 
Transposing 
aspect ratio, 6-18 
pictures, 6-5 
relative positioning, 6-18 
Triggers 
input, 7-3, 7-25 
Truncation 
of metafile data record, 9-19 
TT, 2-7, 3-7, 3-43 


Types 
input data types, 7-2 
lines, 5-30 
markers, 5-52 
prompt and echo, 7-6 
transformation combinations, 8-26 
workstation 
metafile, 9-2 
workstations, 3-3 
default, 3-44 


U 


Unity transformation, 6-5 
Update 
See also Implicit regenerations 
attribute changes, 5-7 
regenerating the surface, 3-12 
releasing deferred output, 3-11 
surface 
segments, 8-10 
the workstation surface, 3-11 
transformations, 3-47 
workstation surface, 3-59 
UPDATE WORKSTATION, 3-59 
Up-vector 
text, 5-78 
User defined 
error handler, 10-1 
metafile data, 9-7 
Utility functions, 8-18 — 


V 


Valuator 
input class, 7-3 
Values 
aitribute, 5-1 
maximum device coordinates, 6-12 
VAX languages, 2-1 
VAXstations 
stroke implementation, 7-3 
using input data records, 7-21 
Vectors 
See also GDPs 
See also Segments 
input coordinates, 7-3 
input time, 7-3 
text up-vector, 5~78 
translation point, 8-17 


Viewports 
See also Transformations 
input priority, 6-10, 7-23 
normalization, 6-5 
overlapping, 7-23 
workstation, 6-12 
Visibility segments, 8-29 
Visual interface 
See also Input 
input prompt and echo types, 7-6 
VMS LINK command, 2-6 
VMS operating system, 2—1 to 2-9 
VT240 
input class implementation, 7-3 


W 


WDSS, 8-2 
See also Segments 
Width 
See also Attributes 
See also Transformations 
character, 5-66 
lines, 5-34 
to height ratio, 6-18 
Windows 
See also Transformations 
workstation, 6-12 
WISS, 3-4, 8-6 
Workstations 
activating, 3-8, 3-14 
clearing the surface, 3-19 
closing, 3-9 
deactivating, 3-8, 3~26 
definition of, 3-3 
description tables, 3-2 
device coordinates, 6—1 
device manipulation 
GKS$ESCAPE, 3-28 
environment, 3-1 
Initialization of, 3-42 
terminating, 3-24 
foreground and background colors, 5-7 
identifier, 3-17 
identifiers 
input, 7-2 
implicit regenerations 
transformations, 6-13 
maximum device coordinates, 6-12 
nominal sizes, 5-3 
opening, 3-7, 3-17 
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Workstations (Cont.) 


output attributes, 5~1 

sending messages to, 3-34 

state list 
attributes, 5—4 
color table, 5-117 
fill area bundle table, 5-122 
pattern style bundle table, 5-129 
polyline bundle table, 5-136 
polymarker bundle table, 5-143 
text bundle table, 5-150 

stored segments, 8-2 

surface, 6—1 

surface control, 3-11 

surface regeneration, 3-12 
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transformations, 1-3, 6-12 to 6-17 
aspect ratio, 6-18 
types, 3-3 
default, 3-44 
hexadecimal, 2-9 
metafile, 9-2 
update 
segments, 8-10 
World coordinates, 6—1 
See also Transformations 
fixed points, 8-17 
origin, 6-2 
WRITE ITEM TO GKSM, 9-22 
Writing to metafiles, 9-3 
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